Description

Feature script name

SipPlayAnnouncement

Applicable contexts

SIP service

SAS Support

Yes

Prerequisite features

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

Typical feature execution points

SipAccess_PartyResponse, SipAccess_PartyRequest, SipMidSession_PartyResponse, SipMidSession_PartyRequest, SipAccess_ServiceTimer, and any SipAccess execution points where an announcement may be triggered, such as SipAccess_SubscriberCheck.

Timer usage

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

The announcement is played by the MRF. The announcements to play are queued in the EarlyMediaAnnouncementInfoQueue 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 EarlyMediaAnnouncementInfoQueue is empty or null then the AnnouncementID session variable is used. If the AnnouncementID session variable is not set, the EarlyMediaAnnouncementQueue is checked. If the EarlyMediaAnnouncementQueue is empty or null then the feature returns without error or side effect to the dialog.

Another feature must be executed prior to the SipPlayAnnouncement feature to set the EarlyMediaAnnouncementInfoQueue and the LanguageConfig.

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 AnnouncementID as keys. If the feature can’t find a profile for the specified language, it will search for a profile just using the AnnouncementID as key.

The SipPlayAnnouncement feature supports UE preconditions if present.

Example Callflows

Play Announcement without Preconditions - OCS Rejects Call

In this scenario, the CCA-I returns with result code 4012 (credit limit reached); and a feature setting the EndSessionAfterAnnouncement session state field to a non-zero value is installed in the SipAccess_CreditLimitReached execution point and runs before PlayAnnouncement, which is also installed in the same execution point. B-Party is never contacted.

sip-play-announcement-feature

The MRF dialog is similar for other types of pre-call announcements, including successful calls.

If the A-Party cancels at any point, the MRF SIP dialog will be torn down appropriately. If there are multiple announcements scheduled (eg the AnnouncementID field has been set as well as at least one entry in the queue, or simply multiple entries in the queue), 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 183 to the calling party, which will be translated to an UPDATE as needed by the Sequential Forked SDP Mediation feature. 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).

Early media play announcement with preconditions and VoWiFi

In this scenario, the caller has resources available as the bearer is WiFi, so there is no value in resource reservation from the caller’s perspective.

Preconditions are in use in case the terminating party does not have resources available at INVITE time. However in this call flow the terminating party is the MRF which does have resources available.

wifi-early-media-announce-barred

The initial INVITE from the UE will contain these media attributes related to QoS.

a=sendrecv
a=curr:qos local sendrecv
a=curr:qos remote none
a=des:qos mandatory local sendrecv
a=des:qos none remote sendrecv

The 183 from the TAS towards the UE will not contain a conf line like this

a=conf:qos remote sendrecv

If in the initial INVITE the UE includes P-Early-Media: supported then the TAS must insert the P-Early-Media: sendrecv header in the 183 response.

This is because some devices includes a P-Early-Media: supported header in the initial INVITE and some MRFs do not include it in the 183 response. Some devices will not play early media unless they receive the P-Early-Media header in the 183 response.

Early media play announcement with preconditions and VoLTE

This case differs from the WiFi case as LTE allows the use of radio resource reservation.

Therefore the INVITE from A indicates that the current state is inactive.

The MRF already has resources available.

volte-early-media-announce-barred

The initial INVITE from the UE will contain these media attributes related to QoS.

a=inactive
a=curr:qos local none
a=curr:qos remote none
a=des:qos mandatory local sendrecv
a=des:qos none remote sendrecv

The 183 from the MRF will contain a conf line like this, instructing A to UPDATE when its resources are available

a=conf:qos remote sendrecv

If in the initial INVITE the UE includes P-Early-Media: supported then the TAS must insert the P-Early-Media: sendrecv header in the 183 response sent upstream. This is because some devices include a P-Early-Media: supported header in the initial INVITE and some MRFs do not include it in the 183 response. Some devices will not play early media unless they receive the P-Early-Media header in the 183 response.

Early media play announcement with preconditions not on MRF

In this scenario, the MRF does not support preconditions.

The call case is a Barring Announcement UE with preconditions supported, resources not initially available.

early-media-announce-barred-mrf-not-support-preconditions

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 (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

EarlyMediaAnnouncementInfoQueue

SipAnnouncementInfo

non-negative

A list of announcements to be played in order. Each announcement specifies an ID and optionally a language to use.

Check the AnnouncementID and EarlyMediaAnnouncementQueue for further announcements to play.

AnnouncementID

Integer

non-negative

ID of the announcement to be played — 0, negative values and null indicate no announcement to play

Poll the EarlyMediaAnnouncementQueue

EarlyMediaAnnouncementQueue

List<Integer>

A list of positive integers

A list of IDs of the subsequent announcements to be played — entries such as 0, null or negative values will be ignored. The AnnouncementID field takes priority over the queue. The element at index 0 will always be treated as the head of the queue. (deprecated)

If the queue itself is null, report featureHasFinished. If one of the entries is null or invalid, increment InvalidAnnouncementIDs and play the next one in the queue.

PlayedAnnouncementIDs

int[]

List of announcement IDs

Announcements which have already been played

Initialized to an empty array

EndSessionAfterAnnouncement

int

The feature will call endSession with the provided error code upon completion if non-zero

Default value is 0 — does not end session

LanguageConfig

String

The RFC 3066 defines language formats, but the feature does not validates the format.

The feature will use the LanguageConfig supplied by the session state field as an input and use it to retrieve the proper announcement profile.

The default value is null, a null value runs the default profile without language configuration.

Outputs

Name Type Format Description

PlayedAnnouncementIDs

int[]

List of announcement IDs

Updated with each announcement ID the feature is invoked to play

EarlyMediaAnnouncementInProgress

SipAnnouncementInformation

Object

Set to the current announcement in progress. Null if no announcement is in progress.

EarlyMediaAnnouncementIsPlaying

boolean

true/false

Set to true when there is an announcement in progress, and false if no announcement is in progress.

Error scenarios

Scenario Handling

Null, negative or 0 found in EarlyMediaAnnouncementQueue

Increment InvalidAnnouncementIDs + retrieve next entry

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

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

Increment SipErrors
Common cleanup actions

MediaServer response timeout

Increment SipErrors
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
Common cleanup actions

Failed to send 183 response

Increment SipSendErrors
Common cleanup actions

Common cleanup actions:

  • Cancel NoResponseTimer

  • Release MRF Leg

  • End session if End Session Flag is set or if announcement is configured with EndSessionOnFailure set to true

  • Increment FeatureFSMCompletions

  • Finish

Feature responses

Response Reason

featureHasFinished

feature has finished

Announcement configuration

Announcements are referenced by id and language code. The configuration of each announcement id is provisioned in the following table:

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 hold 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)

EndSessionOnFailure

Boolean

True if the call should be ended if this announcement fails to play. (Only applies to Early Media 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 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. It is 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 (i.e. using Request URI) (values: true or false)

ServiceParameterType

String

The configured value for the service parameter type e.g. play, voicexml

NoResponseTimeout

Long

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

ICSCFURI

String

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

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

true

voicexml

1000

icscfhost:5054

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 (for example, OpenCloud::::15:en-NZ)

SipAnnouncementResourceConfigProfileTable

Announcement resource addresses and other resource configuration data

SentinelSelectionKey:resourceConfigName (for example, OpenCloud::::voice)

Provisioning interfaces

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

Previous page Next page
Sentinel Express Version 3.0.0