How do feature execution scripts work?

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

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

The Boolean expressions may contain:

  • directives set by features such as feature.continueAndClose

  • Boolean fields from session state such as session.RoamingIndicator

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

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

For example, the Sentinel SS7 default_call_DirectAccess_NetworkPreCreditCheck script:

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

The default_call_DirectAccess_NetworkPreCreditCheck script runs the EmergencyAndSpecialNumber feature.

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

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

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

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

  2. raise feature.featureFailedToExecute to reflect the error

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

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

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

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

Writing feature execution scripts

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

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

Statements

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

The if statement

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

branch

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

Boolean flags

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

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

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

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

Sentinel SIP

 
feature.cannotStart
feature.failedToExecute
feature.issuedWarning

not applicable

Sentinel SS7

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

Diameter

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

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

session.<name of the session state field>

For example, session.SessionHasEnded.

boolean ss
Enum session state fields

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

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

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

enum ss

The while statement

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

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

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

The do-while statement

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

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

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

The run statement

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

run
Note

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

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

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

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

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

String

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

List

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

The return statement

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

Comments

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

Resolving conflicting responses from features

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

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

Common rules

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

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

SS7 rules

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

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

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

SIP rules

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

Diameter rules

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

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

if feature.continueAndClose {
  run releaseAndClose
}

Feature script execution points that are chained together

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

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

  1. are cleared before Session Accept

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

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

  1. are cleared before Network Pre Initial Credit Check

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

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

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

Examples

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

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

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

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

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

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

  • within the context of the network operator (NetworkPreCC)

  • within the context of the session (SessionPreCC)

  • within the context of the subscriber (SubscriberPreCC).

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

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

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

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

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

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

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

If that is the case, we then run ValidateInitialDP.

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

Feature execution script grammar

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

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

tokens
Previous page Next page