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.

Outputs

Name Type Purpose

EarlyMediaAnnouncementInfoQueue

List<SipAnnouncementInformation>

Used to set a new announcement.

EndSessionAfterAnnouncement

int

Used to select a response status to terminate the call with after an announcement is played.

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 DEFAULT to apply to all error codes not otherwise included on the table. Must be equal to the final part of the profile name.

AnnouncementID

long

The ID number of the announcement to be played for the error code. Use 0 (or none in the provisioning interface) to explicitly prevent an announcement from being played.

EndCallWith487Response

boolean

If true, after the announcement is finished, the call will be terminated with a 487 response. If false, the call will be terminated using the original error response code that triggered the announcement.

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=3.1.0].SbbID[name=sentinel.sip,vendor=OpenCloud,version=3.1.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:

  1. No other announcement is in progress or has been queued to play.

  2. The incoming response is a 4xx, 5xx, or 6xx response to an initial INVITE request.

  3. The response was received on a leg that is linked to another leg.

  4. A response with the same status code has been queued to be sent on the linked leg.

  5. 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.

Previous page Next page
Sentinel Express Version 3.1.0