Alert messages are always addressed to a specific login, identified by its GUID.

The transmission of the messages is always mediated by the server: a client ask the server to send messages to another client. There is no direct peer-to-peer communication.

Alert messages can be of various types, and depending on their type they have different associated data. For example,  the 'Msg' is a simple message, its associated data is the message string.

Messages can be represented as XML, e.g.:

  <messages xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.teradp.com/schemas/GN4/1/AlertMessage.xsd">

    <message kind="Msg">

      <data xsi:type="xs:string">First</data>

    </message>

    <message Kind="Msg">

      <data xsi:type="xs:string">Second</data>

    </message>

  </messages>

represents two 'Msg' messages with message strings 'First' and 'Second' respectively.

The 'cmd4 alert' command used to send message can accept a messages XML file, using the '-in' option, e.g.:

cmd4 alert 06ec3f37-a692-4105-8845-35f60fab5e35 -in c:\temp\messages.xml -username xxxx -password yyyy

where xxxx is the name of a GN4 user who can logon to system with sufficient permissions to perform this operation and yyyy is the password.

Note: the above connects to the default connection: should you want to specify the connection or server name, see cmd4 examples.

will send all the messages contained in the 'messages.xml' file to the specified login.

It is also possible to send messages using the do.ashx REST-style API, just POST the messages XML to the URL

../do.ashx?guid=XXXX

where 'XXXX' is the GUID of the destination login (cmd4 uses internally this API call).

The clients receive alerts using a tecnique called long polling. Long polling is a variation of the traditional polling technique and allows emulation of an information push from a server to a client. With long polling, the client requests information from the server in a similar way to a normal poll. However, if the server does not have any information available for the client, instead of sending an empty response, the server holds the request and waits for some information to be available. Once the information becomes available (or after a suitable timeout), a complete response is sent to the client. The client will normally then immediately re-request information from the server, so that the server will almost always have an available waiting request that it can use to deliver data in response to an event. In a web/AJAX context, long polling is also known as Comet programming.

To summarize: they initiate a GET request to the 'alerts.ashx' page on the server, when the server has alerts for the client it will send them as an answer to the GET request, the client will then immediately start another GET request to keep 'listening' for new alerts.

It can happen then when an alert has to be delivered to a client the client is either not listening or it is listening but it is connected to a different servers (there can be multiple application servers in the same system), in these cases there is no pending request that can be used to deliver the alert immediately, so the system queues the messages - saving them in the gn_AlertMessageTable database table:

  Cmd4 version 1.2.909.0 debug

  GN4 command-line client

  Copyright © 2006 - 2010 Tera Digital Publishing

  Language en-US

 

  > alert  a0d98d73-05af-49e8-a886-0387913e3c1a -msg "Hello there!"

  Message(s) queued, the specified login is not listening or is connected to another server

  >

A process on each server will periodically read the queued messages and try to deliver them. Messages older than a (configurable) expiration time will be removed from the table, and so won't be delivered.

There are two parameters in ServerConfig controlling this process:

  <ServerConfig

    xmlns="http://www.teradp.com/schemas/GN4/1/ServerConfig.xsd"

    DatabaseAccessInterval="1000"

    . . .

    TriggersDBCheckPeriod="5"

    AlertsExpirationPeriod="15"

    AlertsPollingPeriod="5">

  . . .

Queued messages older than AlertExpirationPeriod seconds will be removed. The default is 15 seconds.

Each server looks for queued messages to be delivered every AlertsPollingPeriod seconds. The default is 5 seconds.