Details

Feature script name

SipMidCallPlayAnnouncement

Applicable contexts

SIP service

SAS Support

Yes

Prerequisite Features

Any feature setting the MidCallAnnouncementInfoQueue session state field and any feature that sets the LanguageConfig session state field, like Sip Set Language Feature feature.

Typical feature execution points

SipAccess_ServiceTimer, SipAccess_PartyResponse, SipMidSession_PartyRequest, SipMidSession_PartyResponse, and any other mid-session execution point where an announcement may be desired, such as SipMidSession_CreditLimitReached.

Timer usage

Execution-point targeted timer will trigger the feature at the SipAccess_ServiceTimer execution point on expiry.

Behaviour

The announcements are played by the MRF. The announcements to play are queued in the MidCallAnnouncementInfoQueue session state as SipAnnouncementInformation objects each with an announcement ID. The announcement may have an associated language otherwise the LanguageConfig session variable is used. If the MidCallAnnouncementInfoQueue is empty or null then the MidCallAnnouncementID session variable is used. If the MidCallAnnouncementID session variable is not set, the MidCallAnnouncementQueue is checked. If the MidCallAnnouncementQueue is empty or null then the feature returns without error or side effect to the dialog.

Another feature must be executed prior to the SipMidCallPlayAnnouncement feature to set the LanguageConfig and the MidcallAnnouncementId or queue.

All announcements which are played by the feature are appended to the PlayedAnnouncementIDs session state variable. This list of announcements is used by the standard CDR mappers and may be used in custom CDR mappers.

The LanguageConfig String is a language code in RFC 3066 format. Use of the LanguageConfig session state field is optional. The feature will search for a profile using the LanguageConfig and MidcallAnnouncementId as keys. If the feature can’t find a profile for the specified language, it will search for a profile just using the MidcallAnnouncementId.

If there are multiple announcements scheduled in the MidCallAnnouncementInfoQueue, each announcement will be attempted on a new MRF dialog when each previous announcement completes (whether or not it played successfully). Each subsequent announcement necessitates sending another Re-INVITE to the calling party. If the MRF times out at any point, the MRF session will be torn down appropriately and the call will proceed as normal including queued announcements (or be ended, as in the above scenario).

Passive Party Media

The feature supports multiple options for how the passive party’s media streams should be handled while the announcement is playing to the active party. The option to use is specified per-announcement on the SipAnnouncementInformation object by whatever queued the announcement. There are three possibilities, they are:

  • NO_HOLD: The passive party is not put on hold during the announcement, media streams are left as they were.

  • BLACK_HOLE_ONLY: SDP is renegotiated with the passive party so that for the duration of the announcement, all media streams are directed to a black hole IP.

  • FULL_HOLD: SDP is renegotiated with the passive party so that for the duration of the announcement, all media streams are directed to a black hole IP; and additionally the passive party is put on hold by setting the stream status to sendonly or inactive. This is the default.

Call flows

Mid-call low-credit announcement

In this scenario, a feature installed in SipAccess_CreditAllocatedPostCC analyzes the CCA-U and determines that the charged party has low credit. The feature script then runs the MidCallPlayAnnouncement feature. Points of interest are highlighted and explained below the diagram.

mid-call-play-low-credit-announcement

Request from PlayedParty arrives while waiting for answer to PassiveParty hold INVITE

In this scenario, the PlayedParty sends an INVITE or an UPDATE while Sentinel is waiting for the PassiveParty to respond to the hold INVITE. The request is rejected and the announcement is set up as normal.

request-from-playedparty-arrives-waiting-answer-to-passiveparty-hold-invite

PassiveParty does not accept being put on hold

The feature will simply end the announcement and allow the session to continue.

passiveparty-does-not-accept-being-put-on-hold

MRS unresponsive after initial provisional response

When the INVITE request is sent to MRS, Sentinel receives a provisional 100 Trying response which cancels the SIP-Stack-internal request timeout timer; however, no further response is received. Sentinel fires its own ‘noResponse’ timer which ultimately times out. The PlayAnnouncement feature handles the timer event (the feature must be installed in the SipAccess_ServiceTimer execution point) and sends a CANCEL to MRS. The leg is subsequently released. The PAShouldEndSessionWhenFinished session state field indicates whether the feature should send endSession to the core or not. The call may continue afterwards.

mrs-unresponsive-after-initial-provisional-response

Resume call during announcement

For this call flow to work, the Interruptable flag is set to true in the announcement configuration. This tells the feature that the announcement can be stopped by either the call being resumed by the passive party for hold cases, or the call ended if the passive party was to end it with a BYE. A call is put on hold with a long-running announcement. When the holding party resumes the call, a feature detects the resume request and sets the RequestIsResume session state field. When the announcement feature runs and sees this, as well as the interruptable flag, it will stop the announcement and re-connect the two parties for the call to proceed.

mid-call-announcement-interrupted

Leg Manager inputs

Leg Name Type Format Description Behaviour if null/invalid

callingParty

InviteRequest

org.jainslee.resources.sip.SipRequest

See Easysip Javadoc

INVITE received from (and respectively, in the NetworkInitiated case, sent to) the calling party

Runtime exception handled by feature runner

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

Increment InputParameterErrors
Common cleanup actions

SDP

String

Text

Session description

Outgoing request will not contain SDP

LanguageConfig

String

An optional String input containing a language code. The RFC 3066 defines language codes, but the feature does not validate the format.

The value of this fields will be used to get the proper announcement profile. Default is null.

If null the profile search will not consider the language

MidCallAnnouncementInfoQueue

List<SipAnnouncementInformation>

List of SipAnnouncementInformation

List of announcements to play

Check for MidcallAnnouncementId

MidcallAnnouncementId

Integer

Non-negative

ID of the announcement to be played — 0 indicates no announcement to play Increment InvalidAnnouncementIDs (deprecated)

Check the announcement queue

MidCallAnnouncementQueue

List<Integer>

Non-negative

ID of the announcements to be played (deprecated)

Report featureHasFinished

PlayedAnnouncementIDs

int[]

List of announcement IDs

Announcements which have already been played

Initialized to an empty array

PAShouldEndSessionWhenFinished

boolean

Indicates whether the feature will call endSession when finished playing all announcements (deprecated)

Default is false

 

MidCallEndSessionWithAnnouncement

boolean

Indicates whether the feature will call endSession when finished playing all announcements (replaces PAShouldEndSessionWhenFinished)

Default is false

 

MidCallAnnouncementPlayedParty

String

Leg name indicating which party the announcement will be played to

Linked leg will be passivated during announcement (deprecated)

Play to callingParty

RequestIsResume

boolean

Indicates whether the current request is a resume. Set by other features to be read by this one.

Default is false

Outputs

Name Type Format Description

MidCallAnnouncementInProgress

SipAnnouncementInformation

The announcement currently in progress, null if no announcement is in progress.

PlayedAnnouncementIDs

int[]

List of announcement IDs

Updated with each announcement ID the feature is invoked to play

PAShouldEndSessionWhenFinished

boolean

Set to true if the feature is invoked in the CreditLimitReached execution point. Can be cleared by a subsequent feature

Error scenarios

Scenario Handling

Null sessionstate MidcallAnnouncementId

Increment MissingAnnouncementIDs
Finish

MidcallAnnouncementId session state field is ⇐ 0

Increment InvalidAnnouncementIDs
Finish

Null sessionstate SentinelSelectionKey

Increment InputParameterErrors
Common cleanup actions

ACI not provided to the announcement feature

Increment InputParameterErrors
Common cleanup actions

SipSession object not provided to the announcement feature in the activity context interface

Increment InputParameterErrors
Common cleanup actions

Announcement properties not found for announcement ID

Increment InputParameterErrors
Common cleanup actions

Announcement resource config not found for resource config ID

Increment ConfigurationErrors
Common cleanup actions

Failed to send INVITE to Media Server

Increment SipSendErrors
Common cleanup actions

Error received from MRF on Invite

Send Ack with Rejection to played party
Increment SipErrors
Re-invite passive party to resume call if leg not already released
Common cleanup actions

Error received from MRF on Cancel due to played party BYE

Increment SipErrors
Release passive party leg
Common cleanup actions

MediaServer response timeout to INVITE

Send Ack with Rejection to played party
Increment SipErrors
Send Cancel to MRF
Re-invite passive party to resume call if leg not already released
Common cleanup actions

MediaServer response timeout to Cancel

Increment SipErrors
Send Cancel to MRF
Release passive party leg
Common cleanup actions

Failed to send 200 Prack response

Increment SipSendErrors
Report end Session with 500 ServerError to Sip Sentinel core

Failed to send ACK to MRF

Increment SipSendErrors
Common cleanup actions

Failed to send BYE to MRF

Increment SipSendErrors
Common cleanup actions

Failed to send CANCEL to MRF

Common cleanup actions

Failed to send 183 response due to unable to access INVITE from SIPSession

Increment InputParameterErrors
Send ACK to MRF
Cancel NoResponseTimer
Send Bye to MRF
Common cleanup actions

Failed to send 183 response

Increment SipSendErrors
Cancel NoResponseTimer
Send Bye to MRF
Common cleanup actions

Common cleanup actions

Here are some common cleanup actions:

  • If a BYE was received from the played or passive party during the feature, release the other party as well as the MRF leg.

  • If both parties are still present, re-link the legs for B2BUA behaviour.

  • Cancel the NoResponseTimer.

  • Release the MRF Leg (may have been done already).

  • Increment FeatureFSMCompletions.

  • If the PAShouldEndSessionWhenFinished session state field is true, call endSession.

  • Finish.

Feature responses

Response Reason

featureHasFinished

feature has finished

Announcement configuration

Announcements are referenced by ID. The following table shows configuration parameters for provisioning them.

Parameter Type Description

Description

String

Description of the announcement

Id

String

Announcement id (number) plus optional language (eg. 20:en_NZ)

AnnouncementURL

String

URL of the announcement

Delay

Integer

Delay interval between announcement repetitions (in ms)

Duration

Integer

Maximum duration of the announcement (in ms)

Locale

String

Locale of the announcement as a string

MimeType

String

MimeType of the announcement as a string

Repeat

Integer

How many times the media server should repeat the announcement. (-1 means 'forever')

ResourceConfig

String

Name of the profile holding the media resource configuration

SuspendCharging

Boolean

True if charging is suspended during the announcement (only applies to Mid Call Announcements)

Interruptable

Boolean

True if the announcement is interruptable (only applies to Mid Call Announcements)

EnforceOneWayMedia

Boolean

True if media should be unidirectional from the MRF to the played party for the announcement. The feature will modify SDP directionality attributes between the MRF and played party to do this. (only applies to Mid Call Announcements)

Example

Here is an example announcement table configuration:

ID Description AnnouncementURL Delay Duration Locale MimeType Repeat ResourceConfig SuspendCharging Interruptable EnforceOneWayMedia

15

Play message "You have insufficient credit to make this call"

file:msg_15.wav

0

4000

en

audio/vnd.wave

0

default

true

false

false

17

Play tone

file://cts71/annc/CallWaitingReactive.wav

500

100

audio/vnd.wave

2

default

false

false

false

The ResourceConfig is a reference by ResourceId to an entry in the Resource Configuration table with the resource configuration.

Resource configuration

Parameter Type Description

ResourceId

String

ID of this resource configuration
Used by the announcement configuration profile to reference this configuration

MediaServerURI

String

The configured value for the media server URI

RouteDirectToResource

Boolean

The configured value for the route direct to resource
If true, the service sends the Play Announcement INVITE directly to the media server (using Request URI) (values: true or false)

ServiceParameterType

String

The configured value for the service parameter type (for example, play, voicexml)

NoResponseTimeout

Long

The configured number of milliseconds that Sentinel will wait for the MRF to send a response to the INVITE or CANCEL

ICSCFURI

String

The configured value for the I-CSCF URI which is used put in the ROUTE header if RouteDirectToResource is false

Example

Here is an example resource configuration profile:

ResourceId MediaServerURI RouteDirectToResource ServiceParameterType NoResponseTimeout ICSCFURI default

sip:annc-audio@localhost:5260;lr;transport=tcp

true

play

1000

icscfhost:5054

voice

sip:dialog@mediaserver:5061;lr;transport=udp

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

SipAnnouncementProfileTable

Announcement configuration profiles

SentinelSelectionKey:id
(for example, OpenCloud::::15)

SipAnnouncementProfileTable

Announcement configuration profiles

SentinelSelectionKey:id:language
(for example, OpenCloud::::15:en-NZ)

SipAnnouncementResourceConfigProfileTable

Announcement resource addresses and other resource configuration data

SentinelSelectionKey:resourceConfigName
(for example, OpenCloud::::voice)
Previous page Next page
Sentinel Express Version 3.0.0