The alert mechanism implemented in the ibmanager program is about informing the IB-System user about defined events. It is based on certain rules such as the notification calendar and their frequency. This mechanism is made available to logic libraries and their author does not have to handle these rules, it is enough to define them in the alert configuration file.

Each alert is appended with information about the control system application in the form: ApplicationName-InstanceName: alert text, if it has been defined in the Name and Instance attributes of the <Application> element of the ibmanager program configuration file.

Alerts are enabled by defining in the ibmanager program configuration file the <Alerts> element and its Path attribute, pointing to the alert configuration file.

The alert mechanism of the ibmanager program is closely related to the ibalert program. The ibmanager program connects to the ibalert program using the ibprotocol.

Program ibmanager przekazuje programowi ibalert alerty, które zostają przez niego wysłane przy użyciu odpowiednich urządzeń lub połączeń (sms, email itp.).

The ibmanager program passes alerts to the ibalert program, which are then sent using the appropriate devices or connections (sms, email, etc.).

alerts.xml

<?xml version="1.0" encoding="UTF-8"?>
<Config Version="1.1"
        xmlns="http://www.insbud.net/ibmanager/alerts"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.insbud.net/ibmanager/alerts alerts.xsd">
 
  <IbAlert HostName="127.0.0.1" TcpPort="2002" CommunicationTimeout="3000" SecureConnection="true"></IbAlert>
  <Alerts>
    <Alert Id="relay_switched" LogicName="ExampleA" InstanceName="boiler0">
      <Sink RecipientId="0" NotificationType="NM_SMS" RuleName="Critical"/>
    </Alert>
  </Alerts>
  <AlertsMatch Mode="Both"></AlertsMatch>
 
  <Rules>
    <Rule Name="Critical" Priority="0" MinSendInterval="09:00:00">
      <ActivePeriod Day="Week" Start="16:00:00" Stop="18:00:00"/>
      <ActivePeriod Day="Weekend" Start="09:00:00" Stop="20:00:00"/>
      <ActivePeriod Day="Weekdays" Start="16:00:00" Stop="22:00:00"/>
      <ActivePeriod Day="Monday" Start="05:00:00" Stop="05:30:00"/>
    </Rule>
  </Rules>
 
  <Recipients>
    <Recipient Id="0" FirstName="John" LastName="Bree" Phone="+48123456789" Email="j.bree@exampledomain.com"/>
  </Recipients>
 
</Config>

The main element of the configuration file is Config, which has, among others, the Version attribute, which is the version of the alert configuration file. The correct version of the alert configuration file is version 1.1 (for the ibmanager program in version 3.7.4).

If this version does not match the version number currently supported by the program, an error will be reported and the program will terminate.

The remaining elements of the configuration file are described in separate chapters of the documentation.

<IbAlert HostName="127.0.0.1" TcpPort="2002" CommunicationTimeout="3000" SecureConnection="true"></IbAlert>

This is a mandatory element responsible for configuring the connection with the ibalert program.

The element contains the following attributes:

• HostName - DNS name or IP address of the machine where the ibalert program is running.
• TcpPort - TCP port number on which the ibalert program is listening.
• CommunicationTimeout - timeout expressed in milliseconds used in communication with the ibalert program. If any network operation related to the ibalert program lasts longer than the value of this attribute, then it is interrupted and an error is logged.
• SecureConnection - a boolean attribute that indicates whether the ibalert server will use secure SSL communication. If so, it will use the PEM key.pem, local ibpackage certificate (local.cert.pem), and local certificate authority certificate (local.ca.cert.pem). All these files should be located in the license directory (More: ibmanager program configuration file). The recommended value is “true”.

<Alerts>
  <!-- multiple <Alert/> elements -->
</Alerts>

This is a mandatory element responsible for defining all the alerts that the ibmanager program should handle.

The element can contain multiple <Alert> elements.

The element does not contain any attributes.

<Alert Id="relay_switched" LogicName="ExampleA" InstanceName="boiler0">
  <!-- multiple <Sink/> elements -->
</Alert>

This is a mandatory element located in the <Alerts> element. The element is responsible for defining a single alert that is to be handled (passed to the ibalert application) by the ibmanager.

The element contains the following attributes:

• Id - (mandatory) alert identifier. This identifier is assigned in the configuration file of the logic.
• LogicName - (mandatory) the name of the logic in the configuration file of which the alert with the identifier Id is defined.
• InstanceName - (optional) If the attribute is not defined, it means that the alert belongs to the global section of the logic. If it is defined, then it indicates the name of the instance of a given logic in which the alert was defined. If InstanceName is defined, its value cannot be empty.

Having defined an alert, you can assign it a specific sink - i.e., a destination along with the rules it must follow when sending a given alert. The sink is defined by the <Sink> element. One alert can have multiple sinks or none - in which case it will not be handled.

<Sink RecipientId="0" NotificationType="NM_SMS" RuleName="Critical"/>

An optional element located in the <Alert> element. The element is responsible for defining a single sink for the associated alert (parent).

The element contains the following attributes:

• RecipientId - (mandatory) recipient identifier. Recipients are defined in the <Recipients> element. RecipientId is searched among the Id attributes of all <Recipient> elements. If it is not found, then the given outlet will not be handled and such a situation will be logged.
• NotificationType - (mandatory) notification type. It can take the following values:
  • NM_SMS - SMS message. If the indicated recipient does not have an assigned phone number (the Phone attribute is not defined in the <Recipient> element), then the sink will not be handled and such a situation will be logged.
  • NM_EMAIL - email message. If the indicated recipient does not have an assigned email address (the Email attribute is not defined in the <Recipient> element), then the sink will not be handled and such a situation will be logged.
  • RuleName - (mandatory) alert sending rule identifier. Rules are defined in the <Rules> element. RuleName is searched among the Name attributes of all <Rule> elements. If the indicated rule is not found, then the given sink will not be handled and such a situation will be logged. RuleName defines the rules that the ibmanager program will follow when passing a given alert to the recipient of a specific sink.

<AlertsMatch Mode="Both"></AlertsMatch>

An optional element.

Manually defining alerts for all alert templates defined in logics can be cumbersome, especially if all are used and all are to be handled in the same way. Therefore, an element has been introduced that defines the method of matching alert templates from logic configuration files to alerts in the alert configuration file.

The element contains the following attributes:

• Mode - (mandatory) defines how the AlertsMatch functionality should work, it can take the following values:
  • Exact - exact matching. It means that the alert identifier, logic name, and instance name, read from the logic configuration file, must be identical to the values of the Id, LogicName, and InstanceName attributes of the <Alert> element in the alert configuration file.
  • Regex - matching based on regular expressions. It means that the Id, LogicName, and InstanceName attributes of the <Alert> element in the alert configuration file are regular expressions, based on which the alert identifier, logic name, and instance name, read from the logic configuration file, are parsed.
  • Both - Both methods are used. The Exact method is used first. If the alert is not found, then a second attempt is made using the Regex method.

For example:

If an alert with the identifier “RelayEnabled” has been defined in the “Thermostat” logic and ten instances of this logic have been defined, named “t0”, “t1”, …, “t9”, then instead of the need to define ten <Alert> elements in the alert configuration file and repeating the same values each time, differing only in the names of logic instances, it is enough to define one <Alert> element:

<Alert Id="RelayEnabled" LogicName="Thermostat" InstanceName="t[0-9]">
  <!-- multiple <Sink/> elements -->
</Alert>

The AlertsMatch element is optional, when it is not defined, then the Exact method is used.

<Rules>
  <!-- multiple <Rule/> elements -->
</Rules>

A mandatory element, responsible for defining all rules for alerts.

The element can contain multiple <Rule> elements.

The element does not contain any attributes.

<Rule Name="Critical" Priority="0" MinSendInterval="09:00:00">
  <!-- multiple <ActivePeriod/> elements -->
</Rule>

A mandatory element located in the <Rules> element. The element is responsible for defining a single rule for alerts.

The element contains the following attributes:

• Name - (mandatory) identifier (name) of the rule. This name must be unique in the entire set of defined rules. If a duplicate is found, it will be considered a logical error - the program will terminate with an appropriate entry in the logs.
• Priority - alert priority - an unsigned integer. The smaller the value, the higher the priority. This priority is not interpreted by the ibmanager program but is only passed to the ibalert program.
• MinSendInterval - this attribute defines the minimum period at which a given alert can be sent to a specific sink. That is, an alert associated with a given sink will not be sent more frequently than the value of this attribute. This attribute is given in the form HH:MM:SS where HH - denotes hours, MM - denotes minutes, SS - denotes seconds. If an alarm situation occurred in the logic, as a result of which the alert is constantly queued for sending, the alert mechanism will not send the alert to the given sink according to how the alert is reported by the logic, but takes the time of sending the last alert, adds MinSendInterval to it and as a result gets the time at which the alert will be sent again - not earlier, but it can even be later - it depends on the weekly schedule of the rule described later in the documentation.

With a single rule defined, you can define a weekly schedule for the rule, which defines the days of the week and hours at which a given alert can be sent to the recipient. The schedule is defined by the <ActivePeriod> element. A rule can have any number of such elements.

By default, the entire week has blocked the ability to send alerts - if the Rule element is defined without any <ActivePeriod> element, the alert will never be sent to the given alert sink associated with this rule). The ActivePeriod element activates the time range in which the alert can be sent.

Note: if a given alert has been scheduled at least once by the logic for sending, but the rules do not currently allow it to be sent, it will be sent as soon as the rules allow it, even if the alarm situation no longer applies and the logic has stopped reporting the alert. Logics have the ability to “cancel” the sending of an alert, but this is possible when the author of the logic decides to use such a mechanism. In one situation it is desirable, in another not, so this choice lies with the author of the logic.

<ActivePeriod Day="Week" Start="16:00:00" Stop="18:00:00"/>

An optional element located in the <Rule> element. The ActivePeriod element activates a time range for the rule (parent element), during which an alert can be sent.

The element contains the following attributes:

• Day - (mandatory) identifier of the day or days of the week. It can take the following values:
  • Monday
  • Tuesday
  • Wednesday
  • Thursday
  • Friday
  • Saturday
  • Sunday
  • Week - all days of the week
  • Weekend - Saturday and Sunday
  • Weekdays - days from Monday to Friday
• Start - (optional) start time of the range allowing for sending alerts in the format HH:MM:SS. If this attribute is not defined, then its value is set to 00:00:00.
• Stop - (optional) end of the range allowing for sending alerts in the format HH:MM:SS. If this attribute is not defined, thenits value is set to 23:59:59.

<Recipients>
  <!-- multiple <Recipient/> elements -->
</Recipients>

A mandatory element, responsible for defining all alert recipients.

The element can contain multiple <Recipient> elements.

The element does not contain any attributes.

<Recipient Id="0" FirstName="John" LastName="Bree" Phone="+48123456789" Email="j.bree@exampledomain.com"/>

A mandatory element located in the <Recipients> element. The element is responsible for defining a single alert recipient.

The element contains the following attributes:

• Id - (mandatory) recipient identifier, must be unique in the entire set of defined recipients. If a duplicate is found, it will be considered a logical error - the program will terminate with an appropriate entry in the logs.
• FirstName - (mandatory) the first part of the recipient's name (first name).
• LastName - (optional) the second part of the recipient's name (last name).
• Phone - (optional) recipient's phone number.
• Email - (optional) recipient's email address.