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 |
SAS Support |
No |
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 |
SentinelSelectionKey |
com.opencloud.sentinel.common.SentinelSelectionKey |
selection key (for example, |
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 |
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 |
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 |
Announcements can reference variables based on latest CCA see Configuration |
No action |
Error scenarios
Scenario | Handling |
---|---|
Null CorrelationProvider |
Increment ConfigurationErrors |
Sessionstate SentinelSelectionKey is null |
Increment InputParameterErrors |
ACI not provided to the announcement feature |
Increment InputParameterErrors |
No profile for selection key and AnnouncementID in AnnouncementProfileTable |
Increment InputParameterErrors |
No profile for selection key in AnnouncementConfigProfileTable |
Increment InputParameterErrors |
Null TariMillis in AnnouncementConfigProfile |
Increment InputParameterErrors |
Exception invoking RequestReportBCSM on dialog |
Increment ErrorsArmingAbandon |
Dialog object not provided to the announcement feature in the activity context interface |
Increment InputParameterErrors |
Invalid type configured for the announcement ID (Should be tone, message or messages) |
Increment InputParameterErrors |
TooManyInvokesException or ProtocolException whiling sending CTR or PlayAnnouncement |
Increment ErrorsSendingCTRAndPA |
Received SS7 Abort |
Increment Ss7Aborts |
Received SS7 Error |
Increment Ss7Errors |
Received Abandon or Disconnect |
If assisting dialog open, send DFC, close assisting dialog as
prearranged end, release Correlation ID and clear Correlation ID Input |
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 |
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). |
NumberOfRepetitions |
Integer |
The number of times an announcement may be repeated. Valid values: 0 - 127. Note: 0 means the NumberOfRepetitions parameter is not included in the InbandInfo of the PlayAnnouncement operation. |
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 |
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 |
Example announcement table configuration:
ID | Description | Type | Value | ToneDuration | NumberOfRepetitions | AllowDisconnect | InvokeTimeout | CtrConfig | VariableCcaPaths | VariableTypes |
---|---|---|---|---|---|---|---|---|---|---|
1 |
Play message "You have insufficient credit to make this call" |
message |
123 |
3 |
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 |
|
[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 |
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 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 |
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. |
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, |
AnnouncementResourceConfigProfileTable |
ConnectToResource resource configuration |
SentinelSelectionKey:ctrConfigName (for example, |
AnnouncementConfigProfileTable |
Additional resource configuration |
SentinelSelectionKey:configName (for example, |
${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 web interface.