Details

Feature name

VerticalServiceCode

Applicable contexts

SIP service

SAS Support

Yes

Prerequisite features

None

Both prefix and full dial string matching is supported.

Possible modifications to the session include

  • Strip the matched service code from the Request URI and To header

  • End the session with a specific response code

  • Set up session state to play a specific announcement

  • Change the session plan

  • Store a specified value, the matched service code or the dial string suffix to a specified session state field

Session State inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>::::)

For selecting configuration data

N/A

Outputs

Name Type Format Description

OriginalRequestUri

String

The Request URI before any modification by the feature

OriginalNormalisedDialString

String

The normalised dial string before service codes were extracted

DialledVerticalServiceCodePrefixes

List of String

Any prefix service codes found in the OriginalNormalisedDialString

DialledVerticalServiceCodeFullNumber

String

The full match service code if found in OriginalNormalisedDialString after any prefix service codes are removed. Not set if no FullNumber service code found.

DialledSuffix

String

The suffix dial string after all prefix service codes are removed from OriginalNormalisedDialString when no FullNumber match was made. Empty string if FullNumber match occurs.

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

When a matched Action changes the Plan ID.

EarlyMediaAnnouncementInfoQueue

List<SipAnnouncementInformation>

When a matched Action has an announcement ID

<any>

Integer, Long, Boolean, (and their primitives), String, and any Enum type.

Constant value specified in the Action for the service code, converted as specified in the Action and in consideration of the type of the session state field.

<any>

String

Dialled Prefix or Suffix

The service code prefix, or the dialled suffix to that service code may be stored into the String session state field specified in the Action for the service code.

Behaviour

Matching

The feature first extracts the dialled digit String from the Request URI. If no digits can be found the feature finishes.

If the request URI is a tel: URL with phone-context parameter of geo-local then the feature finishes.

If the number is in international format and is not prefixed by the home country code the feature finishes.

If the number is in international format and is prefixed by the home country code then the prefix will be removed before performing analysis. The feature makes use of the Normalization Component to remove the prefix.

The feature then attempts to match the remaining dialstring first against the FullNumber, and failing that against the Prefix AddressLists.

If a match is found …​

  • The Action profile whose name is specified in the matched AddressList Entry is loaded.

  • The actions specified in the Action profile and AddressList entry are performed as described below in Performing Actions.

  • If the match is a prefix match and the action’s AllowAdditionalPrefixes is true, matching is repeated against the remainder of the dial string.

If any matched actions have StripMatch set to true then the Request URI, and To: header are updated to reflect that.

Performing Actions

Play Announcement

If the AddressListEntry’s AnnouncementID is > 0 it is added to the SessionState’s EarlyMediaAnnouncementInfoQueue without chargeForAnnouncement or a specified Language.

End the session with a specific response code

If the Action’s EndSessionResponseCode is > 0 it is used to terminate the session after any queued announcements have played or immediately if no announcements are queued.

Change the session plan

If the Action’s PlanId is a non empty string, it is set into the SentinelSelectionKey. This PlanID will be used from the next ExecutionPoint.

Set a specified session state field to a specified value.

If the Action’s SessionStateFieldName is the name of an actual SesionState field …​

  • if the Action’s SessionStateDataSource is set to SERVICE_CODE_VALUE and the SessionState field is a String field, the matched code is set in that field.

  • if the Action’s SessionStateDataSource is set to SUFFIX and the SessionState field is a String field, the dial string following the prefix code is set in that field. This may include other service codes that have yet to be processed.

  • if the Action’s SessionStateDataSource is set to CONSTANT then

    • The Action’s ValueForConstantDataSource is attempted to be converted according to the Action’s TypeForConstantDataSource.

    • If conversion is successful, the converted value is attempted to be assigned to the SessionState field.

Any failures to find the session state field, or convert or assign a value will generate SAS events, trace logs and the feature reports featureFailedToExecute.

Precedence

If multiple matched AddressList Entries request an announcement, then all such announcements will be queued in the order they are matched.

If multiple matched service code Actions specify an EndSessionResponseCode the last one matched applies.

If multiple matched service code Actions set the same SessionState field, the last matched one applies.

If multiple matched service code Actions change the session plan, the last matched one applies.

Error scenarios

Scenario Handling

Calling Party Leg is null

Throw runtime exception Report featureHasFinished

Leg manager is null

Report featureFailedToExecute

Cannot load Full or Prefix Address List

Report featureFailedToExecute

Invite Request is null

Report featureFailedToExecute

Trigger is not a SIP Request

Report featureFailedToExecute

AddressListEntry specifies an action but the Action profile cannot be found

Report featureFailedToExecute

Missing Normalizer home country code configuration

Report featureFailedToExecute

All digits have been stripped by service code actions

Report featureFailedToExecute

Unable to convert valueForConstantDatasource value to the specified type when assigning to a session state field

Reports featureFailedToExecute with specifics in Tracing and SAS event

Unable to assign a value to specified session state field,

  • Session State field does not exist

  • Specified conversion type is incompatible with field’s actual type

  • Assigning null to a primitive field

  • ValueForConstantDataSource is not a valid enum value for the enum field.

Reports featureFailedToExecute with specifics in Tracing and SAS event

Configuration

Configuration is split between address lists and profile tables. The address lists contain data that needs to be configured by an operator, such as choosing specific service codes for supplied actions and setting which announcement (if any) is appropriate to that action.

The profile table contains data related to how Sentinel or another feature should be triggered to perform certain service code actions. Any new features which have functionality that could usefully be triggered by service codes should supply their own entries in the profile table.

Vertical Service Code address list configuration

The feature uses an AddressListCollection VerticalServiceCode with lists named Prefix and FullNumber for matching prefix and full number service codes respectively.

They are extensions of the standard Address list entry and both have the same structure with the following additional fields.

Parameter Type Description

…​

…​

…​

Action

String

The name of a Vertical Service Code Actions profile to be applied when this service code is found. REM provides a list to select from.

AnnouncementID

Integer

ID of an announcement to be played when this service code is found, set to 0 to disable announcements. REM provides a list to select from.

Example configuration:

Address Action AnnouncementID

*87

MMTel_OIR_ID_Restriction_Current_Session_Disable

0

*63

MMTel_CDIV_Disable

20

The service code lists apply to all subscribers scoped to Sentinel selection key.

Vertical Service Code Actions profile table configuration

Standard and customised actions are stored in a profile table VerticalServiceCodeActions. The table maps an Action name to the actions to perform. The Action name is the result of looking up the dialstring in the Prefix or FullNumber VerticalServiceCode address lists.

Parameter Type Description

actionID

String

The name of this profile without the Sentinel Selection key prefix.

displayName

String

Used by REM to allow the user editing the address lists to choose this Action.

stripMatch

Boolean

If true the matching prefix should be stripped from the Request URI and To: headers. Set to false for the FullNumber addressList otherwise there will be no digits in the request URI and the call will fail.

allowAdditionalPrefixes

Boolean

If true, further matching will be attempted on the remaining dial string. Not applicable to the FullNumber addressslist as that consumes the whole dialled digit string and there is nothing further to match against.

endSessionResponseCode

Integer

If set to a valid SIP error response code, this action will end the session with that response code. Set to 0 when the action should not end the session.

planID

String

This plan ID will be set on the Sentinel selection key when this service code action is performed. Leave unset or empty to not change the service plan.

sessionStateFieldName

String

The name of a session state field to set when this service code action is performed. Leave unset or empty to not set any field.

sessionStateDataSource

String

Determines where to get the value from to set in the session state field, must be one of: 'SUFFIX', 'SERVICE_CODE_VALUE', or 'CONSTANT'.

valueForConstantDatasource

String

The value to put in the session state field if the Session State Data Source is CONSTANT. Will be parsed as specified by sessionStateFieldType.

sessionStateFieldType

String

The type of conversion to apply to valueForConstantDatasource, must be one of: 'INTEGER', 'BOOLEAN', 'LONG', 'STRING' or 'ENUM'. Only applicable when sessionStateDataSource is CONSTANT. Must correspond to the type of the session state field or the assignment will fail.

Example configuration: ${platform.operator.name}:::::MMTel_OIR_ID_Restriction_Current_Session_Disable

Parameter Value

actionID

'MMTel_OIR_ID_Restriction_Current_Session_Disable'

displayName

'MMTel OIR - Disable Identity Restriction For Current Session'

stripMatch

true

allowAdditionalPrefixes

true

endSessionResponseCode

0

planID

''

sessionStateFieldName

'DialledCallerIDRestriction'

sessionStateDataSource

'CONSTANT'

sessionStateFieldType

'ENUM'

valueForConstantDatasource

'OIR_CALLER_ID_UNBLOCK'

Normalization Configuration

The normalizer is used to strip the home country code. See Normalization Component.

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

${PLATFORMOPERATOR}_VerticalServiceCode_AddressListConfigurationTable

Address list configuration

${PLATFORMOPERATOR}:::::VerticalServiceCode:FullNumber: ${PLATFORMOPERATOR}:::::VerticalServiceCode:Prefix:

${PLATFORMOPERATOR}_VerticalServiceCode_AddressListEntryTable

Feature specific Address List entry table

${PLATFORMOPERATOR}:::::VerticalServiceCode:FullNumber:${ADDRESS} ${PLATFORMOPERATOR}:::::VerticalServiceCode:Prefix:${ADDRESS}

${PLATFORMOPERATOR}_VerticalServiceCodeActionsTable

Actions

${PLATFORMOPERATOR}:::::VerticalServiceCode:${ACTION_NAME}

Provisioning interfaces

The feature is provisioned using the Sentinel Features REST API or web interface.

Statistics

VerticalServiceCode statistics are tracked by the sentinel.sip SBB and can be found under the following parameter set in REM:
SLEE-Usage → sentinel.sip service → sentinel.sip SBB → feature → VerticalServiceCode
or with rhino-stats:
"SLEE-Usage.Services.ServiceID[name=sentinel.sip,vendor=OpenCloud,version=2.9.0].SbbID[name=sentinel.sip,vendor=OpenCloud,version=2.9.0].feature.VerticalServiceCode"

Name Type Description 
Started

Counter

Incremented when the feature is triggered.

 
FailedToStart

Counter

Incremented when the feature fails to start.

 
FailedDuringExecution

Counter

Incremented when the feature fails while executing.

 
IssuedWarning

Counter

Incremented when the feature issues a warning.

 
TimedOut

Counter

Incremented when the feature times out during execution.

 
RequestUriIsGeoLocal

Counter

Incremented when the feature does not proceed because the Request URI is geolocal.

 
DialledNumberOutsideHomeCountry

Counter

Incremented when the feature does not proceed because the dialled number is international and outside the home country.

 
NoDialStringInRequestUri

Counter

Incremented when the feature does not proceed because no dial string can be found.

 
FoundDialStringToAnalyse

Counter

Incremented when the feature finds a dial string to analyse.

 
FoundPrefixServiceCode

Counter

Incremented when the feature finds an entry in the prefix address list matching the dial string.

 
FoundFullNumberServiceCode

Counter

Incremented when the feature finds an entry in the full number address list matching the dial string.

 
NoServiceCodesFound

Counter

Incremented when the feature finds no service codes in the dial string.

 
SessionStateFieldSet

Counter

Incremented when an Action sets a session state field.

 
PlanIdSet

Counter

Incremented when an Action changes the session plan.

 
AnnouncementQueued

Counter

Incremented when an Action queues an announcement.

 
PreparedToEndSession

Counter

Incremented when an Action schedules the session to end.

 
ServiceCodeStrippedFromRequestUri

Counter

Incremented when an Action strips a matched service code from RequestURI.

 
EndSessionInstructed

Counter

Incremented when the feature ends the session.

 
UpdatedUris

Counter

Incremented when the feature updates the Request URI, and the To: header.

 
FailedToUpdateUris

Counter

Incremented when the feature is unable to update the URIs.
Previous page Next page
Sentinel Express Version 2.9.0