Difference between revisions of "Event Handler"

Latest revision as of 14:01, 21 November 2023

Event Handler - Block Diagram

The ICX-AlphaCom and AlphaCom XE servers are intercom servers of which the main task is to enable uni- and bi-directional speech. In order to be able to meet as many customer requirements as possible when it comes to special features an Event Handler has been implemented. The underlying idea is that by customer-programming this event handler functionality can be implemented which is not part of the standard feature list. The event handler is unique in the world of intercom. It is what gives the server its flexibility and makes it possible to meet most, if not all, customer requirements.
The Event Handler is based on the software concept that when the intercom functions run, they report 'events' to a part of the software called the Event Handler. The event can be described as a trigger that sets off an action in the system depending on the information entered in AlphaPro, the programming tool for the ICX-AlphaCom. In this way, the Event Handler provides a powerful engineering tool for configuring system behavior to meet requirements from customers.

Actions can be simple, just to operate a relay under certain circumstances. Actions can also be programmed using a scripting language and can include conditional statements. An action can itself trigger a new event, making it possible to start a chain of actions.

The principle

Events

Events are generated inside the ICX-AlphaCom software when interesting things happen. Events follows a fixed format, with the following parameters:

Owner
Event type
State change : ON/OFF
Related-to

The owner is source which triggers the event. The following possible owners are defined:

A single station
A group of stations (UDP group) with common behavior
The scheduler, the internal ICX-AlphaCom realtime clock
External Data Input, a data port set up to receive ASCII text strings from external devices

The Event type is a number which tell what sort of event occurred. Event type is divided into a Main event and Sub-Event. Main events are listed below. Only some of the Main events use the Sub-Event. In the case of the scheduler the event is the ‘minute tick’.

State change: Most of the events are modeled as a state which goes ON and OFF. But some events does not fit to that concept, then only a ON event is reported.

Related-to is specific for the feature which reports the event. It can be the other station in a conversation, or the sending station of a mail or CallRequest.

For some features in AlphaNet, the owner of an event can be in a different node. Then the EVENT REPORT message sent to the owning exchange, where the event is processed. Conversation Outgoing is an example of such an event.

Event Rules

Event handler Rules are what you program in the Event Handler window in AlphaPro. An Eventhandler Rule has two main parts:

A condition, which matches specific Events
An action, which specifies what should happen when a Event matches a Condition.

Stations can trigger many different types of event.
Many events can trigger an action when the event is activated and when the event is de-activated, for instance event type 07: Conversation – Incoming. The On/Off action can be differentiated by the ‘When Change To’ flag.
Events can be, but don't have to be, related to a specific directory number or a group of stations, for instance:

Owner: Station 1
Event: Conversation - Outgoing
Related to: Directory number 102
When change to: ON
Action: RCO 2 ON

In this case the relay connected to RCO 2 will only be activated if 'Station 1' is in conversation with a station with directory nr 102, AND if Station 1 was the station which made the call. If 'Related to' was not specified, that same relay would be activated on any call which Station 1 would make.

Events Types

The list shows the available event types, grouped by function.

Event Type	No.	When triggered
Single Station Events
Audio	01	When audio is played in the speaker
Door Open - Automatic Lock	03	When the Code Lock feature is dialed
Station in Use	04	When a station becomes busy or free
Microphone Open	05	When the microphone is alive
Faulty Station Line	13	When a station is reported faulty or OK
M-key	31	When the M-key is pressed or released
Off-hook	32	When the handset is lifted or replaced
C-key	35	When C-key is pressed or released
Feature From Idle	37	When a feature is dialed from idle
Additional call info	39	Feature status, such as: User denied access, call to busy station, etc.
Station Fault	43	Reports various station and ENA amplifier errors
Conversation Events
Conversation Incoming	07	When a call is received
Conversation Outgoing	08	When a call is made
Conversation	44	When a call is received
Private Ringing mode	09	During private ringing for incoming call
Private Ringing Outgoing	33	During private ringing for outgoing call
Door Opening - During Conv.	02	When door opening feature (digit 6) is activated during conversation
SIP progress event	36	During setup of call to SIP trunk
Recording	40	Control recording session
Mail (Call Queue) Events
Received Mail	10	When a mail or a call request is received
Call Requester Mode	11	When a station sends a Call Request
Priority Mail Present	06	When a mail with priority level 100 (programmable) is present in the mail queue
Priority Mail in Idle	12	When a priority mail is present, and the station is not in conversation
Mail Timeout	20	When a mail times out
New Current Mail	23	When the current mail in the queue is changed
New First Mail	24	When a new mail arrives first in the queue
Group & Conference Events
Simplex Conference Audio	16	When listening to simplex conference, and the $VOX command is activated
Simplex Conference Member	17	When a station joins a simplex conference
Open Duplex Conf. Ringing	18	During ringing to an open duplex conference
Open Duplex Conf. Connect	19	When a station connects to an open duplex conference
Dynamic group inclusion	38	NOT IN USE
Event Triggers
Event Trigger	15	When dialing a directory number with feature number 52, 85, 95 or 105
Event Trigger with parameter	25	When dialing Event Trigger feature 95 or 105, preceded by a directory number or digit
Start: Event Trigger with param.	26	When dialing a directory number with feature number 95
Event Timeout	21	When a timer started by the $ST command expires
Station Input or Station DAK key	30	When a station input or DAK key is pressed
Scheduling
Scheduler (Minute Tick)	22	When matching the specified date (or weekdays) and time
EDI - External Data Input
External Data Input	28	When receiving ASCII data on EDI port
System Events
System Status	27	When a device is reported up or down
AlphaNet Link	29	When an AlphaNet link is reported up or down
Board Status	34	When a board is reported up or down

Action Commands

There are two types of Action Commands which can be used by the Event Handler, Built-In Action Commands and Data Protocol Commands.

Both types of commands can include parameters and macros (e.g. %1.dir and %clk(8))

Built-In Action Commands

Built-in Action Commands are three- or four-letter commands. The commands are case-insensitive as from AMC 08.20. Most of the Built-In commands also have a Data Protocol implementation.

Command	Description	From AMC ver.
PRS	Audio Program to Station
PRG	Audio Program to Group
CNG	Simplex Conference to Group
MST	Mail to Station
MGR	Mail to Group
MPP	Mail to Pocket Pager
AMS	Alarm Message to Station
AMG	Alarm Message to Group
RCO	Set Remote Control Output
EDO	Send text to serial port External Data Output EDO 1 - 4
LOG	Send text to exchange’s log port (including date/time)
IND	Indicator control for CRMIV LEDs, buzzer etc.	AMC 07.20
GIND	Indicator control to a group of station .	AMC 11.02
OWN	Modify Event Owner (%1) and/or Related_To (%2) values	AMC 07.60
WUDD	Write a value to an User Defined Data UDD
TMP	Write a string to a temporary variable
PAUSE	Pauses the event handler command interpreter for 100 ms	AMC 08.20
IF/ENDIF	Conditional statement	AMC 08.20
STOP	Stops the execution of the rest of the action string	AMC 08.20
LOOP/ENDLOOP	Looping statement	AMC 11.00
BREAK	Break out of Loop	AMC 11.00

Data Protocol Commands

Data Protocol Commands are using ACDP commands on the Simple Link Layer format. The commands begin with $ or @.

The most relevant data protocol commands for the Event Handler and for RCIs are listed in the table below. Follow this link for a complete list of all Data Protocol Commands

Message	Short name	Message no, Hex	Description
Station Connect Operations
CALL_SETUP	CALL	0x0008	Sets up a conversation between two users
DISCON_ST		0x008E	Disconnect station from ongoing feature
PAR_RING		0x0098	Add a Parallel Ringer station to a call in ringing state
Station Keyboard & Display emulation
DIAL_DIGITS	DD	0x0050	Simulate digit dialing from a station
DIAL_DAK		0x0094	Dial DAK on a station
PLAY_DAK	PD	0x009C	"Dial sequence" for playback.
M_KEY	M	0x0054	Order station to press M-key
M_KEY_RELEASE	MREL	0x0055	Order station to release M-key
C_KEY	C	0x0058	Order station to press C-key
DISPLAY_TEXT	DSPL	0x005A	Send text and control characters to a station
Station Features and Status
PROGRAM	PROG	0x0001	Set audio program for single station or a predefined group of stations
PROG_CONF	CONF	0x0004	Set Simplex conference for predefined group of stations or a single station
CONF_TALK		0x008B	Set Simplex conference speaker
CONF_TALK_STOP		0x008C	Stop station form feeding Simplex conference
O_DUPL_CONF	ODC	0x006F	Include/exclude a station or a group into/from an Open Duplex Conference
ALARM_MSG	ALRM	0x0007	Set up (or disconnect) an ASVP Alarm message to a single station or a predefined group of stations
CALL_TRANSFER	TRF	0x0044	Set or remove call transfer for a station
SET_REQ_TRANSF	SCRT	0x002B	Set transfer of Call Request for an intercom station
SET_ABSENCE	SABS	0x0028	Set absence status for an intercom station
WAKE_UP		0x0047	Register or remove wakeup request
SET_GRP_FILT	GFLT	0x007D	Set group call filter for a station
GROUP_MEMBERSHIP	GRM	0x0081	Set group membership in NVRAM for a station
SET_STATION_COS	SSC	0x0090	Set COS membership in NVRAM for a station
MODIFY_COS_CONTENTS	MCC	0x0091	Modify feature membership in COS in NVRAM
TEMP_PROG	TPROG	0x0096	Temporarily "mute" program distribution to a station
VOL		0x009B	Set station volume
SET_RCO	SET	0x0018	Activate IP Station output
SILENT CALL	SC	0x0077	Set a station in silence call mode for next feature activated
Station Mail Operations
SEND_MAIL	SM	0x0031	Send a mail message to an intercom station
SEND_TXT_MAIL	STM	0x0032	Send a mail message with free text to an intercom station
CANCEL_MAIL	CANM	0x0065	Delete one or more mail/call request/alarm messages queued at a station
SET_MAIL_TIMEOUT	SMT	0x0082	Set the timer of a mail queue entry
COPY_MAIL	CPYM	0x0083	Send a copy of a mail in own queue to a new destination (station or group)
MAILQ_NAVIG		0x008D	Do operation on mail queue, or step current mail in mail queue
DELETE_MAIL	DELM	0x0034	Delete a mail entry in the queue for an intercom station
General Exchange Control
SET_SYSTEM_TIME	SST	0x0027	Set the internal clock to the given date and time
PUT_STRING	PUT	0x0073	Output String to Exchange serial port after adding appropriate framing depending on selected port
LOG_STRING	LOG	0x0075	Output String to System Log
EXECUTE_COMMAND	X	0x004F	Send a command string to the exchange to be executed there
EVENT_REPORT	ER	0x0067	Report an event to the event/action system
SET_TIMER	ST	0x008F	Start or stop a timer
WRITE_USER_DEF_DATA	WUDD	0x008A	Write User Defined Data (UDD)
SET_DIRNO_TXT	SDT	0x0077	Change the display text of a directory number (station or feature)
SMALL_RESET		0x00BC	Simulates Small Reset sent from ICX-AlphaCom web interface

Context Parameters and macros

Action commands used in the Event Handler can contain context parameters and macros. They both return a value.

Context Parameters are related to the actual event, and refer to the involved station(s) or functions. A parameter always starts with the character "%". Context parameters are useful for defining the action of a rule where the condition is a UDP_group.

%1: the parameter is associated with the Owner field
%2: the parameter is associated with the Related to field
%3: the parameter is associated with the When change to field

A macro is unrelated to the event itself. It reads information from the memory (nvram) or performs a calculation. Also a macro always starts with the character "%".

Macros and parameters can be nested freely, and makes it possible to build complicated expressions.

List of context parameters

Parameter	Short name	Returned value	From version
%1.phy	%1p	The physical number	AMC 07.20
%1.dir	%1d	The directory number
%1.nam	%1n	The name (display text)	AMC 08.00
%1.exp	%1e	The User defined parameter
%1.udp		The UDP group memberships for station	AMC 10.21
%1.dak	%1k	The number of the DAK key containing a specified string	AMC 08.00
%1.nod		The node number	AMC 08.03
%1.ref		The node and directory number as a complete NET_OBJ_REF. %1.ref is equivalent to "L(%1.nod) %1.dir"	AMC 08.20
%1.mpri		Priority of the mail. Available in mail related ON events only	AMC 08.20
%1.mfre		Free-text of station mail if available, else ”-”. Available in mail related events only
%1.tag		Mail tag. Unique mail identification. Available in mail related events only	AMC 08.10
%1.dev		The Device number	AMC 09.03
%1.brd		The board number (1 - 25)	AMC 09.03
%1.port		The port (1 - 32) within board	AMC 09.03
%3.chg %chg	%3c	%chg(ON_txt,OFF_txt) returns "ON_txt" when the event goes ON, "OFF_txt" when the event goes OFF Example: LOG “Door %1.dir is %chg(OPEN ,CLOSED)“ Result, event ON: - “Door 123 is OPEN ” Result, event OFF: - “Door 123 is CLOSED”	AMC 07.20
%3.rft %rft	%3r	Action command parameter which substitutes the parameter with a text describing the on/off transition of the event. Some events can be reported many times (e.g. line errors), and it's possible to have different actions depending on if this is the first time, or a Refresh. %rft(normal_text,refresh_text) returns <refresh_text> if this is a refresh transition. <normal_text> otherwise.
%sev		Read sub-event number	AMC 09.03
%edi		Read EDI text input	AMC 10.00
%1.fea		Feature of directory number	AMC 13.1.3.1

Note: %2 can be used instead of %1. %2 will refer to the 'Related To' field instead of the 'Owner' field.

List of macros

Macro	Description	From version
%op	Macro for numeric calculations	AMC 08.20
%udd	Read a UDD (User Defined Data variable)	AMC 08.20
%tmp	Read Temporary variable	AMC 10.00
%sng	Find next group which station is member of	AMC 08.20
%gns	Find next member station of group	AMC 08.20
%ges	Find next station of Mutual exclusion group	AMC 11.0.3.0
%sgm	Is station member of group	AMC 08.20
%clk	Read current date and time on format yyyy-mm-dd hh:mm:ss	AMC 08.20
%clkyear	Read current year	AMC 08.20
%clkmon	Read current month	AMC 08.20
%clkday	Read current day	AMC 08.20
%clkhour	Read current hour	AMC 08.20
%clkmin	Read current minute	AMC 08.20
%clksec	Read current second	AMC 08.20
%clkwday	Read current day of week (1 = Monday, 7 = Sunday)	AMC 08.20
%1.clk, %1.clkyear etc	Read the scheduling tick time	AMC 08.20
%gnv	The value of the NVRAM-parameter	AMC 09.05
%scutc	String extraction by character position	AMC 10.00
%scutf	String extraction by field number	AMC 10.00
%sscan	String extraction by text scan	AMC 10.00
%scmp	String compare	AMC 10.00
%strlen	Return length of a string	AMC 11.1.3.0
%lbd	Return local board of the AMC card	AMC 10.53
%prog	Return current program active on a station. 0 = no program	AMC 10.53
%dfmt	Convert decimal value to hex, octal or ASCII	AMC 11.0.1.2
%1.pag %2.pag	%1.pag returns the A-subscriber pager id. %2.pag returns the B-subscriber pager id	AMC 10.30
%paf	Read PA failure state (IP-ARIO)	AMC 11.2.3.1
%pai	Read default DAK index of PA failure state (IP-ARIO)	AMC 11.2.3.1
%pap	Read default Mail priority of PA failure state (IP-ARIO)	AMC 11.2.3.1
%prci	Read physical rci state of an IP Station or IP-ARIO rci	AMC 11.2.3.1
%prco	Read physical rco state of an IP Station or IP-ARIO rco	AMC 11.2.3.1
%rphy	Read physical number from directory number	AMC 11.2.3.1
%rdir	Read directory number from physical number	AMC 11.2.3.1
%tin	Returns current number of trunk channels in use towards a specific trunk	AMC 11.2.3.3
%syse	Returns state of system event	AMC 11.2.3.4
%nip	Return IP address of remote node	AMC 11.2.3.4
%rn	Return node number of a directory number	AMC 11.2.3.4
%vol	Return station current volume setting	AMC 11.2.3.11
%syspar	Return state of system parameter	AMC 11.5.3.4
%sfg	Return failure state of IP stations in a station group	AMC 12.5.3.0
%mcm	Return the physical number of the Mix Controller associated to the Mixer Channel	AMC 12.3.3.1
%sxc	Return the simplex conference channel number that the station is listening to.	AMC 12.3.3.1
%busy	Return the busy/free state of a station.	ICX 1.0.3.1, AMC 13.1.3.3
%tnsf	Return the first parameter of a directory number.	ICX 1.0.3.1, AMC 13.1.3.3
%tnss	Return the second parameter of a directory number.	ICX 1.0.3.1, AMC 13.1.3.3
%tnst	Return the third parameter of a directory number.	ICX 1.0.3.1, AMC 13.1.3.3
%mch	Return the first station-channel (phy) related to the mixer_station (phy) that is member of the conference (no 1-99).	ICX 1.0.3.1, AMC 13.1.3.3

Formatting

Text adjustment parameters can be added to all %xxx macros

%xxx(width,filler)

width: Length of field

If ‘<’ is put immediately after the width, it means left-adjustment. Default is right adjustment

filler: If width is wider than the returned value, the specified filler character is filled in

Typical fillers are

” ” (space)

”0” (leading zero)

”F” (MPC protocol)

The filler can be omitted: %xxx(width). Then ” ” (space) will be used as filler if required. It is not allowed with space between the formatting parameters

Examples:

%1.dir

Minimum:         %1.dir        - Example result:  “123”
MPC format:      %1.dir(4,F)   - Example result:  “F123”
Two last digits: %1.dir(2)     - Example result:  “23”

%1.nam

Minimum:           %1.nam      - “Mr. Smith”
5 last characters: %1.nam(5)   - “Smith”
12 char, right :   %1.nam(12)  - “   Mr. Smith”
12 char, left :    %1.nam(12<) - “Mr. Smith   ”

%udd (assuming decimal value 65 is stored in UDD 12)

%udd(12)         - “65”
%udd(12,4)       - “  65”
%udd(12,4<)      - “65  ”  
%udd(12,4,f)     - “ff65”  
%udd(12,4<,f)    - “65ff”

%clk

Minimum:           %clk      - “2009-10-16 12:59:35”
8 last characters: %clk(8)   - “12:59:35”
10 char, left :    %clk(10<) - “2009-10-16”

Free text

A free text in built-in event handler commands are written in double quotes "".

<br

Comments

The Event Handler allows line comments by prefixing the line with an exclamation mark (!).

Any line in the event handler starting with ! will not be executed. This does not support inline comments.

Comments are supported as from AlphaCom sw 13.1.3.1

Example:

IF %busy(4)
!Station 4 is busy
stop
ENDIF
!Station 4 is free
$CALL L101 L104

Escape sequences

Escape sequences can be used for two purposes:

to use non-printable characters in action strings
quoting: ignore special meaning of a character in eventhandler parser.

Some frequently used escape sequences:

\r = Carriage Return
\n = Line Feed 
\xhh = hh is any ASCII value in HEX

Some ASCII values:

\x0D = Carriage Return (CR)
\x0A = Line Feed (LF)
\x02 = Start of Text (STX)
\x03 = End of Text (ETX)
\x06 = ACK

Find more Escape sequences.