☰
Navigation :

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

▲ 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. 
~ncc_oper/bin/acsProfile -u / -G 1 | grep <announcement ID on SRF>

Note that announcement names are not stored on the NCC SLC and can therefore not be selected by name.

    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.

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:

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.

If the announcement status is not able to be turned into a number:

Announcement status is not readable.

If the announcement status is not recognised as a valid announcement status code:

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)
▲ 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.
    }
}

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.

    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.

If an individual varparts table parameter is not provided in a table:

Individual variable part definitions must be provided in a table.

If an individual varparts table parameter does not include both TYPE and VALUE:

Individual variable part definitions must provide 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:

Numeric string type variable parts must be provided 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:

Unsigned and date type variable parts must be provided as a real number.

If an individual varparts table parameter’s TYPE is unrecognised:

Unknown variable part type <TYPE provided>; must be one of 'nstring', 'unsigned', or 'date'.

In addition, all errors for ncc.announcement.play can also be raised by this function.

Usage This function is identical to ncc.announcement.play but allows variable parts to be supplied to be passed to the network.

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.

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