MICROMEDIA INTERNATIONAL ALERT: Driver - ixarmaxml ALERT Alarm Monitoring and Advanced Call- Management Author: Jens Eberle Sites: 10 Company: Micromedia International Date: 12/4/20142014 Version: 1.0.3 Ref. : ALERT_Treiber ixarmaxml_en.docx [Kommentare ] ixarmaxml Driver configuration Mailing To CC Company Attachments 04/12/20142014 ixarmaxml Driver configuration 1/10
Content Alarm Monitoring and Advanced Call-Management... 1 Introduction... 3 Requirements... 3 ixarma Connection Data... 3 ALERT - ixarma connection... 3 ALERT ixarma Driver Interface... 4 Service Message (Send a Message )... 5 Two types of alarm cases... 5 Used parameters of the alarm definition window... 6 Alarm creation in ixarma (dynamic/static)... 7 Additional User - Commands... 8 Redundancy... 9 Alert.ini... 10 ixarmaxml.ini configuration... 10 04/12/20142014 ixarmaxml Driver configuration 2/10
Introduction ixarma is a web based server system to monitor safety and building equipment. This document describes the connection type between ALERT (client) and the ixarma web server. Requirements ALERT Version 3.6 rev. 1 Build 27 or higher IXARMAXML license option must be activated System requirements correspond to the requirements of ALERT. Link: compatibility and system requirements or visit www.micromedia-int.com and go to SUPPORT\FAQ\ALERT. ixarma Connection Data To connect to the ixarma web server following information are needed: URL (Master) Recommended, TCP/IP Port 443 (HTTPS), allow incoming and outcoing traffic. From version 1.0.0.2 and later the HTTP protocol and the TCP/IP port definition was implemented, e.g. http://demo.inax.ch:583 GET/POST Method differentiation (default, GET) User name Password To use the redundant mode o URL (Slave) 2. and if applicable the URL of the 3. web server ALERT - ixarma connection It s a client/server connection, where ALERT act as client. We differ two ways: a. Direct mode The ixarma Server URL will be directly used in the address bar of the user media. Switching to the redundant URL, will happen after the call cycles failed - according to the team or user call definition. 04/12/20142014 ixarmaxml Driver configuration 3/10
b. Heartbeat/redundant mode (recommended on bad quality networks) The URL will be defined in the driver GUI, after the successful configuration of the access data, a query request (Heartbeat) will be sent from ALERT to the ixarma server to check if the server is reachable. The Timeout to send Heartbeat (s) can be defined in the drivers interface. Also the retry Heartbeat period can be configured, it means, if the defined amount of reties was reached and the redundant mode is activated, the driver will change to one of the slave URLs. ATTENTION: When changing from one mode to the other one, please make sure that the address bar of the user media is direct mode or heartbeat mode confirm! ALERT ixarma Driver Interface Here you will see the Graphical User Interface (GUI) of the ixarma driver, it serves the configuration of the driver. ALERT driver name System ID Automatic call acknowledgement, please activate it! At now, there is no option available of the ixarma server to do the call acknowledgement automatically. To show the driver activities in the journal Each alarm in ALERT will send one alarm to ixarma.please check the box, otherwise only the last alarm will be send. Heartbeat Tiemout, should be bigger than one minute, otherwise the ixarma server can refuse the request. If Hearbeat = 0 the redundant mode will be disabled! Hearbeat retries: Amount of attempts before switching to the slave URLs Username and password, all Servers (Master/Slave) are using the same login data. Direct URL mode, if axtivie, the Heartbeat-/Redundanz mode will be switched off. Please set then the URL directly in the address bar URL (Master) if the redundant mode is activated, please configure the Slave URLs (URL2, URL3). 04/12/20142014 ixarmaxml Driver configuration 4/10
Service Message (Send a Message ) According to the ixarma specification, there are 4 event types of an alarm, set (K), reset (G), acknowledge (Q) and set&reset ($). In the case sending a user message ( send a message of ALERT) then the set&reset event will be used. This means the alarm in ixarma will be only once triggered and call its procedure just once, then abort. Please use the short message field to define the alarm which should be set in ixarma = alarm point id <apid>. Please note, by sending a service message the <bez> will be ServiceCallofALERT and the <family> will be ALERT. Two types of alarm cases When there is an alarm in ALERT, an alarm request will be send to the ixarma web server. If ALERT receives an OK the call will be acknowledged, otherwise if it will receive a NOTOK ALERT will follow its call cycle definition. Case 1: In the Alarm definition window of ALERT, a set and reset (optional acknowledgement) action must be used, otherwise the Alarm in ixarma will not be set back. If the same alarm will be triggered a second time the alarm in ixarma will do nothing. 04/12/20142014 ixarmaxml Driver configuration 5/10
Case 2: When using the command @! in the user driver address field, an alarm in ixarma will be set with a following reset. In this case ALERT must not send extra a reset/ack to the ixarma server. This means an alarm procedure will only once triggered in ixaram and after the procedure abort. Used parameters of the alarm definition window To send a message to ixarma the driver is generating a XML string. In ALERT following fields are used. In the image below you will see the relation between ALERT and ixarma. 1. Alarm name in ALERT is the Alarm identifier in ixarma 2. priority, in ixarma only allowed 0 3! 3. Alarm processing = K (Kommend) 4. Reset = G (Gehend) Acknowledgement = Q (Quittieren) 5. Alarmmessage = Alarmtext 6. Shortmessage in ALERT is the AlarmPoint ID in ixarma (this will be set the ALARM!) 7. Alarm group of alert = Alarmpläne <family> XML Strin (green) of the image above: this message will be sent to ixarma. https://demo.inax.ch/axis2/services, /AlarmService/alarm?version=1&xml=<msg><apid>DPALERT</apid><sysid>JENSEBERLE- PC</sysid><event>K</event><bez>DPALERT1</bez><prio>0</prio><family> </family><callerid>alert</callerid><text><![cdata[dpalert1 Alarm kommend]]></text></msg> 04/12/20142014 ixarmaxml Driver configuration 6/10
ATTENTION: The alarm reset and acknowledgement action configuration must use the same short message field entries and the same call groups as the alarm processing action. If the alarm reset and acknowledgement action aren t used, please use then the address field of the driver in the user settings, please set the command @$!. Recommendation: If using the alarm reset and acknowledgement action, use the @G! command for the first ixarmaxml Driver and the second one without parameter. This will do a reset of the alarm in ixarma before setting it. This is a kind of a protecting mechanism to make sure the alarm on the server will be set! Alarm creation in ixarma (dynamic/static) The ixarma server can allow dynamic alarm creation. For this reason a script, running on the ixarma server must be modified to evaluate the request of ALERT. Otherwise (static), an alarm must be created and exist on the ixarma server before trigger an alarm in ALERT.!STATIC! - If an alarm will be raised in ALERT, but isn t configured on the ixarma server, nothing will happen. 04/12/20142014 ixarmaxml Driver configuration 7/10
Additional User - Commands It s possible to add specific commands to the number/address field of the user media ixarmaxml Driver. So it s possible to add the following commands @K!, @G! and @$! to set = K, reset = G and to do a set and reset = $ of an event in ixarma. With @AP: an alarm point can be directly set on the server. If using the Direct Mode, first the URL must be entered followed by the commands, e.g.: https://pri.ixarma.ch/axis2/services @$! This is used for special cases, please find the commands here in short: @K! describes a set event: <event>k</event> @G! describes a reset event: <event>g</event> @Q! describes an ack event: <event>q</event> @$! describes a set with follwoing reset event: <apid>$alarmpunktid</apid> in this case the <event> is always defined a K in ixarma @$*! = <apid$*alarmpunktid>, please ask Inax.ch @QR! = send query request to the ixarma server @GET! and @POST! Choose the GET or POST method, default GET, see ini file. @AP: when used an alarm point can directly be created in ixama by using the address bar of the users media. Attention, this command must be placed after the other commands: e.g.: @G! @AP:AlarmPunktID1 @SYSID: will set the System ID <sysid> @CALLERID: = <callerid> @FAMILY: = <family> E.g.: https://pri.ixarma.ch/axis2/services @FAMILY:AlarmGruppe1; @SYSID:2; The following screenshot shows an example configuration used in direct mode. 04/12/20142014 ixarmaxml Driver configuration 8/10
Attention: using the command parameters will override the default ones. It means, the URL in the address bar is having a higher priority that the definition of the ixarmaxml Driver GUI, it s also the same for family, sysid, etc. Redundancy Direct mode Per Team If the first user in a team cannot be reached the relief user (with the redundant URL) will be called. Or per user Heartbeat mode The redundancy only works if the Heartbeat Timeout is greater than 0 and when the Redundant mode is activated. Hearbeat retries, defines the amount of heartbeats with failure before switching to a slave URL. If no slave URL will work, the original master URL will be set. In this case, please verify the URL, Firewall settings,login date and the readiness of the ixarma server. During this time the heartbeat method is running in a loop mode and checks the ixarma driver configuration each minute. 04/12/20142014 ixarmaxml Driver configuration 9/10
Alert.ini If the ixarmaxml.dll wasn t installed during the setup, please add follwing entriy to the [drivers] section: ixarmaxml=4700,ixarmaxml.dll,0,3 Info: Please don t forget to enable the license option! Only after the activation or in demo mode the ixarmaxml driver will work. ixarmaxml.ini configuration To enable the advanced driver log of ixarmaxml, please set the parameter TraceInFile to TRUE afterwards with the next restart of ALERT the ixarmaxml_log.txt will be created (if the heartbeat mode is activated and the timeout is set to 1 minute, the file size per day will around 500KBs.). 04/12/20142014 ixarmaxml Driver configuration 10/10