Actions

Event Handler

From Zenitel Wiki

Revision as of 14:38, 5 May 2010 by Aksel (talk) (→‎List of macros)

See also: Event Handler applications

Event Handler - Block Diagram

The AlphaCom exchange is an intercom exchange 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 exchange 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 AlphaCom exchange. In this way, the Event Handler provides a powerful engineering tool for configuring system behaviour 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 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 behaviour
  • The scheduler, the internal 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 - Automatick 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
Conversation Events
Conversation Incoming 07 When a call is received
Conversation Outgoing 08 When a call is made
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
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
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
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, preceeded 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 DAK key as RCI 30 When a 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
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 ASCII commands in 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 wake­up 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
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)



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 %1e The UDP group memberships for station  
%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 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 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.  
%sev   Read sub-event number AMC 09.03
%edi   Read EDI text input AMC 10.00
%1.pag   Return pager number related to station 1 / 2 AMC 10.30


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
%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 sceduling 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.00.3.2
%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.00



Formating

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 "".

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
Retrieved from "https://wiki.zenitel.com/w/index.php?title=Event_Handler&oldid=17994"