Announcements
Announcement Functions
Overview
You can use the NCC API to play specific announcements, with or without variable parts.
Statuses
Responses from ACS are parsed and assigned an enumerated status. These can be directly accessed for their value or their text equivalent:
ncc.announcement.status = {
value = {
["COMPLETED"] = 0,
["INTERRUPTED"] = 1,
["ABANDONED"] = 2,
["ERROR"] = 3
},
text = {
[0] = "completed",
[1] = "interrupted",
[2] = "abandoned",
[3] = "error"
}
}
The statuses for completed and interrupted both indicate successful playing of the announcement.
Telephony
Playing an announcement requires telephony to be enabled for the active call. If this is not valid, e.g. the caller has hung up or a previous announcement resulted in the abandoned status, then attempting further telephony actions will result in a run-time error within the NCC engine and the call being dropped with an alarm. Whether telephony is active or not is not enforced by the Logic Node nor available on request from NCC, so you should ensure you maintain a local flag that indicates the status of the call when playing announcements.
Functions
Note that announcement names are not stored on the NCC SLC and can therefore not be selected by name.
If duration, repetitions, or interval have been provided but are not able to be turned into a real number, one of the following errors will be raised as appropriate: If the announcement status is not able to be turned into a number: If the announcement status is not recognised as a valid announcement status code:
▲ ncc.announcement.play (id, duration, repetitions, interval)
Parameters
id
The announcement VAID to play. These numbers can be retrieved from the NCC global profile by using the Oracle tool acsProfile and matching it to information available in the SMS screens, e.g.
~acs_oper/bin/acsProfile -u / -G 1 | grep <announcement ID on SRF>
duration
The announcement duration to provide to the SRF. Optional; defaults to 0.
repetitions
The number of announcement repetitions to provide to the SRF. Optional; defaults to 0 (play once only).
interval
The interval, in seconds, between announcement repetitions to provide to the SRF. Optional; defaults to 0.
Returns
An enumerated announcement status.
Errors
If the provided id is not able to be turned into a number, the following error will be raised:
Announcement ID must be a positive, non-zero number.
Announcement duration, if supplied, must be a real number.
Announcement repetitions, if supplied, must be a real number.
Announcement repetition interval, if supplied, must be a real number.
Announcement status is not readable.
Unrecognised announcement status code <status code> returned.
Usage
This function instructs the ACS engine to play the given announcement with the supplied parameters, if any. The NCC platform is responsible for the setup and translation of this announcement, as defined in the NCC screens.
ncc.announcement.play (3)
Note that the table indices are used for the order of parts in the message to the network. These values must begin at 1 and increase sequentially.
If an individual varparts table parameter is not provided in a table: If an individual varparts table parameter does not include both TYPE and VALUE: If an individual varparts table parameter has a TYPE of nstring but a VALUE that cannot be parsed as a string: If an individual varparts table parameter has a TYPE of unsigned or date but a VALUE that cannot be parsed as a positive number: If an individual varparts table parameter’s TYPE is unrecognised: In addition, all errors for ncc.announcement.play can also be raised by this function.
The types of variable parts allowed are:
* nstring: a string of hexadecimal characters, parsed as INAP digits by the SRF.
* unsigned: a unsigned integer value, parsed as an INAP number by the SRF.
* date: an epoch integer value, parsed as an INAP date by the SRF.
▲ ncc.announcement.play_variable (id, varparts, duration, repetitions, interval)
Parameters
id
As for ncc.announcement.play.
varparts
A (possibly empty) table of variable parts, formatted as:
{
[1] = {
TYPE = "nstring|date|unsigned",
VALUE = <unsigned integer value>|"<numeric string value>"
},
[2] = {
-- etc.
}
}
duration
As for ncc.announcement.play.
repetitions
As for ncc.announcement.play.
interval
As for ncc.announcement.play.
Returns
As for ncc.announcement.play.
Errors
If the provided varparts are not supplied in a table:
Announcement variable parts must be provided in a table.
Individual variable part definitions must be provided in a table.
Individual variable part definitions must provide both TYPE and VALUE.
Numeric string type variable parts must be provided as a string.
Unsigned and date type variable parts must be provided as a real number.
Unknown variable part type <TYPE provided>; must be one of 'nstring', 'unsigned', or 'date'.
Usage
This function is identical to ncc.announcement.play but allows variable parts to be supplied to be passed to the network.
local vp = {
[1] = { TYPE = "unsigned", VALUE = 3 },
[2] = { TYPE = "unsigned", VALUE = 45 }
}
ncc.announcement.play_variable (5, vp)
▲ ncc.announcement.successful (result)
Parameters
result
The result value from a previous ncc.announcement.play or ncc.announcement.play_variable function call.
Returns
true if the announcement was played successfully, otherwise false.
Errors
None.
Usage
This is a shortcut function to check the provided result against the two “successful” announcement statuses for completion or interruption.
if (ncc.announcement.successful (ncc.announcement.play (3)) then
-- continue with other announcements
else
-- error or abandon
end