This feature analyses the dialled number to identify its components, and modifies the session as required to give effect to service codes it finds in the process.
Details
Feature name |
VerticalServiceCode |
|---|---|
Applicable contexts |
SIP service |
SAS Support |
Yes |
Prerequisite features |
None |
Session State inputs and outputs
Inputs
| Name | Type | Format | Description | Behaviour if null/invalid |
|---|---|---|---|---|
SentinelSelectionKey |
com.opencloud.sentinel.common.SentinelSelectionKey |
selection key (for example, |
For selecting configuration data |
N/A |
Outputs
| Name | Type | Description |
|---|---|---|
AnalysedHomeCountryCode |
String |
The home country code as configured in the normalizer. |
AnalysedDialledNumber |
TaggedNumber |
The original dialled number with its components tagged. |
OriginalRequestUri |
String |
The Request URI before any modification by the feature. |
SentinelSelectionKey |
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 |
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
The feature has two functions. One is to identify and set up behaviour for service codes. The other is to identify parts of the number that are relevant to normalization.
For service codes, 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.
For normalization related analysis, the feature will identify any of the following components within the number:
-
The international escape code
-
The international format indicator (i.e. "+").
-
The national dialling prefix
-
The home network dialling prefix
-
The home country dialling code.
In most cases, the feature only looks for normalization components in the part of the number that’s left after service codes have been identified. The exception to this is the international format indicator followed by the home country code (e.g. +64 for New Zealand), this will be identified anywhere that it appears within the number. Also note that if the feature finds the international format indicator followed by a foreign country code, it will stop looking for further service codes and will not attempt to identify normalization components.
The feature will output the results of its analysis as a tagged number in the AnalysedDialledNumber session state field.
A tagged number is a data structure that breaks down a number into labelled components.
It can be used by other features to simplify their own number analysis or manipulation procedures.
Service code 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 skips service code matching.
The feature then attempts to match the remaining dial string 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
AllowAdditionalPrefixesistrue, 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 service code 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
SessionStateDataSourceis set toSERVICE_CODE_VALUEand the SessionState field is a String field, the matched code is set in that field. -
if the Action’s
SessionStateDataSourceis set toSUFFIXand 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
SessionStateDataSourceis set toCONSTANTthen-
The Action’s
ValueForConstantDataSourceis attempted to be converted according to the Action’sTypeForConstantDataSource. -
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.
Service code 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.
Number Tagging Examples
As the feature analyses a number it tags each part and outputs the results to AnalysedDialledNumber session state field.
The following table gives examples for how a number will be tagged based on the following configuration:
-
Home Country Code: 64
-
International Escape Code: 00
-
National Dialling Prefix: 0
-
Home Network Dialling Code: 55
-
Prefix Service Codes: *67, *800
-
Full Number Service Codes: 200
| Dialled Number | Tags |
|---|---|
+6455123456 |
|
+6312345678 |
|
006412345678 |
|
055123456 |
|
+64*6755123456 |
|
*67055123456 |
|
+64200 |
|
*8000064123456 |
|
12345678 |
|
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 |
Reports featureFailedToExecute with specifics in Tracing and SAS event |
Unable to assign a value to specified session state 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 |
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 |
String |
The type of conversion to apply to |
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 configuration is used for identifying normalization related components in the number. 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=4.0.0].SbbID[name=sentinel.sip,vendor=OpenCloud,version=4.0.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. |
