The Play Announcement feature plays an announcement to the calling party during call establishment or after the called party disconnects. The announcement is played by the MSC/GMSC gsmSRF.

Description

Feature name

PlayAnnouncement

Applicable contexts

SS7 service

Prerequisite features

The id of the announcements to be played is set in the AnnouncementID session variable. If the AnnouncementID session variable is not set (null) or set to 0, no announcement is played and the feature returns without error or side effect to the dialog.

Another feature must be executed prior to the PlayAnnouncement feature to set the AnnouncementID.

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

The announcement can be played using one of the following modes:

  • Using ConnectToResource only, to connect to an SRF integrated with the controlling MSC.

  • Using EstablishTemporaryConnection and an assisting dialog to connect to a non-integrated SRF.

  • Using Connect to redirect the call to an IVR or announcement device. When using this mode the call ceases to be controlled via Sentinel.

If desired the announcement mode can be configured based on address lists matching the global title digits in the dialog’s CallingPartyAddress, the triggering MSC address, the subscriber address (as determined by Sentinel), or the subscriber’s IMSI. Alternatively the announcement can always be played using the same announcement mode.

Session state inputs and outputs

Inputs

Name Type Format Description Behaviour if null/invalid

AnnouncementID

Integer

Any integer

ID of the announcement that is to be played

Increment MissingAnnouncementIDs
Report featureHasFinished

SentinelSelectionKey

com.opencloud.sentinel.common.SentinelSelectionKey

selection key (for example, <platform>::::)

For selecting configuration data

Report featureCannotStart, featureHasFinished

CanRelayDialog

boolean

true or false

True if the assisting dialog has not been accepted yet

Not nullable

ResponderSccpAddress

com.opencloud.slee.resources.cgin.SccpAddress

SccpAddress

The SCCP Address to use as the responding address in the Open Response instead of the address provided by the stack, or null to leave the address unchanged

Use the address provided by the stack

LatestEventReportBCSM

com.opencloud.slee.resources.cgin.callcontrol.CCEventReportBCSMArg

CC-DataTypes.EventReportBCSMArg

Once the first event report has been received abandon is no longer required

Abandon will be armed

CallType

com.opencloud.sentinel.common.CallType

One of: MobileOriginating, MobileTerminating, MobileForwarded, NetworkInitiated, EmergencyCall

Session type of this call for determining from configuration which party address to lookup

Report featureCannotStart, featureHasFinished

LatestOcsAnswer

org.jainslee.resources.diameter.ro.types.CreditControlAnswer

Credit-Control-Answer

Announcements can reference variables based on latest CCA see Configuration

No action

Outputs

Name Type Format Description

CanRelayDialog

boolean

true or false

True if the assisting dialog has not been accepted yet

Error scenarios

Scenario Handling

Null CorrelationProvider

Increment ConfigurationErrors
Report featureFailedToExecute

Sessionstate SentinelSelectionKey is null

Increment InputParameterErrors
Report featureFailedToExecute

ACI not provided to the announcement feature

Increment InputParameterErrors
Report featureFailedToExecute

No profile for selection key and AnnouncementID in AnnouncementProfileTable

Increment InputParameterErrors
Report featureFailedToExecute

No profile for selection key in AnnouncementConfigProfileTable

Increment InputParameterErrors
Report featureFailedToExecute

Null TariMillis in AnnouncementConfigProfile

Increment InputParameterErrors
Report featureFailedToExecute

Exception invoking RequestReportBCSM on dialog

Increment ErrorsArmingAbandon
Report featureFailedToExecute

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

Increment InputParameterErrors
Report featureFailedToExecute

Invalid type configured for the announcement ID (Should be tone, message or messages)

Increment InputParameterErrors
Report featureFailedToExecute

TooManyInvokesException or ProtocolException whiling sending CTR or PlayAnnouncement

Increment ErrorsSendingCTRAndPA
Report featureFailedToExecute

Received SS7 Abort

Increment Ss7Aborts
If assisting dialog open, send DFC, close assisting dialog as prearranged end, release Correlation ID and clear Correlation ID Input
Report featureFailedToExecute

Received SS7 Error

Increment Ss7Errors
If assisting dialog open, send DFC, close assisting dialog as prearranged end, release Correlation ID and clear Correlation ID Input
Report featureFailedToExecute

Received Abandon or Disconnect

If assisting dialog open, send DFC, close assisting dialog as prearranged end, release Correlation ID and clear Correlation ID Input
Report featureFailedToExecute

Tari expiry

If not useAssistingDialog, Increment TariExpiries If assisting dialog open, send DFC, close assisting dialog as prearranged end, release Correlation ID and clear Correlation ID Input
Report featureFailedToExecute

Feature responses

Response Reason

featureFailedToExecute

ss7Error

featureHasFinished

feature has finished

Configuration

Announcement configuration

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

Parameter Type Description

Description

String

Description of the announcement

Id

Integer

Announcement ID

AnnouncementType

AnnouncementTypeEnum

The announcement type, one of [message, tone, messages]

Value

Integer[]

Value of the message/tone ID (or IDs if 'announcementType' is 'messages') to be played.

ToneDuration

Integer

Duration of a tone announcement in seconds. Valid values: not set, 0 - 65535. Note: 0 means infinite duration. (This is an Integer4 ASN.1 type).

VariableCcaPaths

String[]

An array of CCA xpath expressions

VariableTypes

String[]

An array of type names. Each entry has to be one of [integer, number, date, time, price]

AllowDisconnect

Boolean

Determines if automatic disconnect of the gsmSRF is allowed when the announcement is complete.

ResetTssf

Boolean

Indicates whether or not a ResetTimer operation will be sent before the announcement is played to reset the Tssf timer.

InvokeTimeout

Long

Invoke timeout in milliseconds. In conjunction with the Tssf Reset Margin it is used to set the invoke timeout of the PlayAnnouncement operation and to determine the value to reset the Tssf timer to via the ResetTimer operation before the announcement begins (if ResetTssf is true). 1000-3600000 milliseconds.

CtrConfig

String

Reference to resource configuration to use with ConnectToResource

IvrAddressCalledPartyNumber

CalledPartyNumber

The IVR address is only required if the announcement mode is CONNECT. It is specified in called party number string format, which includes comma-separated name value pairs with names one of: address, nature, numberingPlan, routingToInternalNetworkNumber. See CalledPartyNumber for more information.

Example announcement table configuration:

ID Description Type Value ToneDuration AllowDisconnect InvokeTimeout CtrConfig VariableCcaPaths VariableTypes

1

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

message

123

N

10000

srf1

2

Play tone

tone

23

250

N

1000

3

Play messages "You have insufficient credit to make this call", and "Call the topup line"

messages

123,124

N

10000

4

Play message with variable 1 assigned time granted

message

34

N

10000

[/MultipleServices
CreditControl
[ServiceId = 0]
/Granted-Service-Unit/CCTime]

[integer]

The Play Announcement feature may set variables based on fields from session state (latest CCA is supported). The Sentinel XPath Language Component is used to reference fields in the CCA. For example, /MultipleServicesCreditControl[ServiceId = 0]/GrantedServiceUnit/CCTime references the amount of time granted for service with id 0.

The CtrConfig is a reference to an entry in the Resource Config table with the ConnectToResource configuration.

Resource config

Parameter Type Description

Name

String

Name of this CtrConfig. It is used by the announcement configuration profile to reference this configuration.

ResourceAddressCalledPartyNumber

CalledPartyNumber

The resource address in called party number string format, which includes comma-separated name value pairs with names one of: address, nature, numberingPlan, routingToInternalNetworkNumber. See CalledPartyNumber for more information.

Example resource configuration profile:

Name

ResourceAddress

srf1

The ResourceAddress choice NONE is selected when the ResourceAddress is not set.

Announcement mode

The announcement mode determines how the announcement will be played:

Internally using ConnectToResource only, to connect to an SRF integrated with the controlling MSC.

Using EstablishTemporaryConnection and an assisting dialog to connect to a non-integrated SRF. There are two sub-modes of this mode:

Combined mode, where the assisting MSC address, SCF id, and correlation id are all combined into the assistingSSPIPRoutingAddress parameter of the EstablishTemporaryConnection operation argument.

Separate mode, where the assisting MSC address, SCF id, and correlation id all use separate fields in the EstablishTemporaryConnection operation argument.

Using Connect to redirect the call to an IVR or announcement device. When using this mode the call ceases to be controlled via Sentinel.

The announcement mode is determined first by address list interrogation (see table below), followed by the Sentinel Selection Key configuration if no matching address list configuration was found.

Address lists

The Play Announcement feature supports four different address lists for determining the announcement mode:

Address List Name Default Search Mode Description

OriginatingSccpAddressList

longest prefix match

Uses the the global title digits of the the incoming dialog’s CallingPartyAddress.

MscAddressList

longest prefix match

Uses the address string of the MSCAddress parameter of the incoming InitialDP or InitialDPSMS.

SubscriberAddressList

exact match

Uses the subscriber address for the session.

SubscriberImsiList

exact match

Uses the subscriber IMSI for the session.

The address lists actually searched by the Play Announcement feature are determined by the Sentinel Selection Key configuration. The default search mode for each list can be changed via the configuration for the corresponding address list. An address list will only be searched if the feature can determine a suitable address for the lookup. For example, if the incoming dialog has no global title digits in the CallingPartyAddress then the OriginatingSccpAddressList will not be searched, even if specified in the configuration.

Sentinel selection key configuration

Various other parameters related to playing the announcement are set in a configuration that may be scoped to the Sentinel selection key:

Parameter Type Description

AnnouncementLists

AnnouncementList[]

A list of Address List names specifying which address lists to search for the announcement mode. The address lists will be searched in the order given in this list.

Default Mode

AnnouncementMode

The announcement mode to use if address list lookup fails to find an announcement mode. One of [INTERNAL, ETC_COMBINED, ETC_SEPARATE, CONNECT]

Assisting SSP IP Routing Address Generic Number

GenericNumber

Address of the Assisting MSC. Only required if using an ETC announcement mode.

Combined Mode SCF ID

String

The SCF ID of Sentinel to use in ETC_COMBINED mode. Only required if using an ETC_COMBINED announcement mode.

Separate Mode SCF ID

Byte[]

The SCF ID of Sentinel to use in ETC_SEPARATE mode. Only required if using an ETC_SEPARATE announcement mode.

Use Correlation Delimiter

Boolean

Flag indicating if a delimiter digit (hex 'b') should be used between the assisting MSC address and the SCF ID when using the ETC_COMBINED mode. Only relevant if using this mode.

Tssf Reset Margin

Integer

The number of seconds added to the announcement duration used to reset the Tssf timer using the ResetTimer operation during announcement playing. This is just a safety margin.

Tari Millis

Long

The Tari timer value in milliseconds

Announcement playing signalling flows

If AllowDisconnect=false or is not set or has invalid value, the PlayAnnouncement.disconnectFromIPForbidden is set to true and the announcement component will send the DFC; otherwise it will not.

The call flow to be used (AllowDisconnect=true):

MSC <---- RT ----- Sentinel
MSC <---- CTR ---- Sentinel
MSC <---- PA ----- Sentinel
MSC <- DELIMITER - Sentinel
MSC ----- SRR ---> Sentinel
MSC - DELIMITER -> Sentinel

The call flow to be used (AllowDisconnect=false):

MSC <---- RT ----- Sentinel
MSC <---- CTR ---- Sentinel
MSC <---- PA ----- Sentinel
MSC <- DELIMITER - Sentinel
MSC ----- SRR ---> Sentinel
MSC <---- DFC ---- Sentinel
MSC <- DELIMITER - Sentinel

In the case of multiple announcements, all the play announcements in the list will be sent together to the gsmSRF. The FSM will handle all of the SRR expected from the gsmSRF before returning.

The call flow to be used (all AllowDisconnect=false):

MSC <---- CTR ---- Sentinel
MSC <---- PA ----- Sentinel
MSC <---- PA ----- Sentinel
MSC ----- SRR ---> Sentinel
MSC ----- SRR ---> Sentinel
MSC <---- DFC ---- Sentinel

Error handling

The Play Announcement feature may encounter a number of different errors, for example:

  • required configuration state may be missing

  • required configuration parameters may be invalid

  • operation errors sent by the initiating or assisting MSC may be encountered

In all error cases the feature returns the featureFailedToExecute result and exits. A feature script can test for this condition and react accordingly, for example the script could allow the call to continue regardless, or could release the call instead.

Examples of some error call flows:

SRR expected but not received:

MSC <---- CTR ---- Sentinel
MSC <---- PA(requestAnnouncementComplete=true) ---- Sentinel
Invoke timeout
MSC ----> PE(NO_LINKED_RESPONSE) ---> Sentinel

This is the standard case when requestAnnouncementComplete=false (that is, no SRR expected but we still get the provider error due to the protocol definition)

MSC <---- CTR ---- Sentinel
MSC <---- PA(requestAnnouncementComplete=n) ---- Sentinel
Invoke timeout
MSC ----> PE(NO_LINKED_RESPONSE) ---> Sentinel

Reject:

MSC <---- CTR ---- Sentinel
MSC <---- PA ---- Sentinel
MSC ----> PE(REMOTE_REJECT) ---> Sentinel

Configuration profile naming

Configuration Profile Table Name Description Profile Naming

AnnouncementProfileTable

Announcement configuration profiles

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

AnnouncementResourceConfigProfileTable

ConnectToResource resource configuration

SentinelSelectionKey:ctrConfigName (for example, OpenCloud::::srf1)

AnnouncementConfigProfileTable

Additional resource configuration

SentinelSelectionKey:configName (for example, OpenCloud::::config)

${PLATFORMOPERATOR}PlayAnnouncementAddressListConfigurationTable

Address list configuration

${SELECTIONKEY}:PlayAnnouncement:${AddressListName}

${PLATFORMOPERATOR}PlayAnnouncementAddressListEntryTable

Feature specific Address List entry table

${SELECTIONKEY}:PlayAnnouncement:${AddressListName}:${ADDRESS}

Provisioning interfaces

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

Previous page Next page
Sentinel Express Version 2.7.0