This feature optionally plays an announcement based on the response status when an INVITE error response is being forwarded to the calling party during call setup.
Details
Feature name |
ErrorCodeAnnouncement |
|---|---|
Applicable contexts |
SIP service |
SAS Support |
Yes |
Prerequisite features |
None |
Session State inputs and outputs
Inputs
| Name | Type | Purpose |
|---|---|---|
SentinelSelectionKey |
SentinelSelectionKey |
Used to select error code mappings. |
EarlyMediaAnnouncementInfoQueue |
List<SipAnnouncementInformation> |
Used to see if announcements have already been set. |
EarlyMediaAnnouncementInProgress |
boolean |
Used to determine if an announcement is already playing. |
Configuration
This feature uses profile configuration to map SIP error response codes to announcements to be played.
These mapping are kept in a profile table called ErrorCodeAnnouncementMappingTable.
Entries in the table are scoped by Sentinel Selection Key along with the value of the error code they correspond to.
For example, a profile may be named: Metaswitch:Metaswitch::::404.
Each profile has the following fields:
| Name | Type | Description |
|---|---|---|
ErrorCode |
String |
The error code the mapping applies to. Can be set to |
AnnouncementID |
long |
The ID number of the announcement to be played for the error code. Use |
EndCallWith487Response |
boolean |
If true, after the announcement is finished, the call will be terminated with a |
Provisioning interfaces
The feature is provisioned using the Sentinel Features REST API or web interface.
Statistics
ErrorCodeAnnouncement 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 → ErrorCodeAnnouncement
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.ErrorCodeAnnouncement"
| 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. |
PlayingAnnouncement |
Counter |
Incremented when the feature queues an announcement to be played. |
SkippingDueToAnnouncementInProgress |
Counter |
Incremented when the feature skips response analysis because an announcement has already been set. |
SkippingDueToAlreadyAnnouncedUpstream |
Counter |
Incremented when the feature does not play an announcement because it has detected that an error announcement has already been played by a downstream node. |
SetCustomHeaderOnFinalResponse |
Counter |
Incremented when the feature successfully adds a header on the outbound final response to indicate that it has played an error announcement. |
UnableToSetCustomHeaderOnFinalResponse |
Counter |
Incremented when the feature fails to add a header on the outbound final response to indicate that it has played an error announcement. |
Behaviour
The feature is triggered by any incoming SIP response received during call setup.
Before attempting to play an announcement, the feature will check that a number of conditions have been met:
-
No other announcement is in progress or has been queued to play.
-
The incoming response is a 4xx, 5xx, or 6xx response to an initial INVITE request.
-
The response was received on a leg that is linked to another leg.
-
A response with the same status code has been queued to be sent on the linked leg.
-
No other error code announcement has been played by a downstream node on the same network.
If any of these conditions are not met, the feature will finish execution without attempting to play an announcement.
If the conditions are met, then the feature will check the ErrorCodeAnnouncementMappingTable for a profile that matches both the status code of the incoming response, and the current Sentinel selection key.
If no such profile is found the feature will look for a profile labelled DEFAULT (while still matching the selection key).
If a profile is found using either method, and it indicates that an announcement should be played (i.e. the profile has a non-zero AnnouncementID);
then the feature will queue an announcement with the indicated AnnouncementID.
The feature will also give an instruction to terminate the call after the announcement has been played.
Depending on the value of the EndCallWith487Response field on the profile, the status code of the response used to terminate the call will either be 487, or the code from the original incoming response.
In the event no profile is found, the feature will finish execution without queuing an announcement.
The SIP Play Announcement Feature is responsible for actually playing the announcement.
Suppression Of Repeat Announcements
The feature uses a custom SIP header (OC-Error-Code-Announced) to prevent multiple error code announcements being played in the same call by different AS instances.
When the feature is invoked on an incoming error response it will check for the presence of this header on the response. If it is present, the feature will not attempt to play an error code announcement.
When the feature does play an announcement, it will add this header to the outbound final error response that is sent after the announcement is complete.
The header value indicates the original error code that triggered the announcement (even when the actual response status code is changed to 487).
This header should be stripped before it leaves the network, therefore multiple error code announcements could still be played if some legs of the call are not in the same network.
