====== ibmanager program Alerts ======

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 [[en:ibmanager:ibmanager-config#<Application>|<Application>]] element of the **ibmanager** program configuration file.

Alerts are enabled by defining in the **ibmanager** program configuration file the [[en:ibmanager:ibmanager-config#<Alerts>|<Alerts>]] element and its **Path** attribute, pointing to the alert configuration file.

The alert mechanism of the **ibmanager** program is closely related to the [[en:ibalert:start|ibalert]] program. The **ibmanager** program connects to the **ibalert** program using the [[en:ibprotocol:start|ibprotocol]].

Program **ibmanager** przekazuje programowi [[pl:ibalert:start|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 [[en:ibalert:start|ibalert]] program, which are then sent using the appropriate devices or connections (sms, email, etc.).

===== Example alert configuration file =====

<code xml 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>
</code>

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> ====

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

This is a mandatory element responsible for configuring the connection with the [[en:ibalert:start|ibalert]] program.

The element contains the following attributes:

  * **HostName** - DNS name or IP address of the machine where the [[en:ibalert:start|ibalert]] program is running.
  * **TcpPort** - TCP port number on which the [[en:ibalert:start|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 [[en:ibalert:start|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: [[en:ibmanager:ibmanager-config|ibmanager program configuration file]]). The recommended value is "true".

==== <Alerts> ====

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

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

The element can contain multiple [[en:ibmanager:ibmanager-alerts#<Alert>|<Alert>]] elements.

The element does not contain any attributes.

=== <Alert> ===

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

This is a mandatory element located in the [[en:ibmanager:ibmanager-alerts#<Alerts>|<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 [[en:ibmanager:ibmanager:logics:start|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 [[en:ibmanager:ibmanager-alerts#<Sink>|<Sink>]] element. One alert can have multiple sinks or none - in which case it will not be handled.

== <Sink> ==

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

An optional element located in the [[en:ibmanager:ibmanager-alerts#<Alert>|<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 [[en:ibmanager:ibmanager-alerts#<Recipients>|<Recipients>]] element. **RecipientId** is searched among the **Id** attributes of all [[en:ibmanager:ibmanager-alerts#<Recipient>|<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 [[en:ibmanager:ibmanager-alerts#<Recipient>|<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 [[en:ibmanager:ibmanager-alerts#<Recipient>|<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 [[en:ibmanager:ibmanager-alerts#<Rules>|<Rules>]] element. **RuleName** is searched among the **Name** attributes of all [[en:ibmanager:ibmanager-alerts#<Rule>|<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> ====

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

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 [[en:ibmanager:ibmanager-alerts#<Alert>|<Alert>]] element in the alert configuration file.
    * **Regex** - matching based on regular expressions. It means that the **Id**, **LogicName**, and **InstanceName** attributes of the [[en:ibmanager:ibmanager-alerts#<Alert>|<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 [[en:ibmanager:ibmanager-alerts#<Alert>|<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 [[en:ibmanager:ibmanager-alerts#<Alert>|<Alert>]] element:

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

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

==== <Rules> ====

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

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

The element can contain multiple [[en:ibmanager:ibmanager-alerts#<Rule>|<Rule>]] elements.

The element does not contain any attributes.

=== <Rule> ===

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

A mandatory element located in the [[en:ibmanager:ibmanager-alerts#<Rules>|<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 [[en:ibmanager:ibmanager-alerts#<ActivePeriod>|<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 [[en:ibmanager:ibmanager-alerts#<ActivePeriod>|<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 ==

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

An optional element located in the [[en:ibmanager:ibmanager-alerts#<Rule>|<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> ====

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

A mandatory element, responsible for defining all alert recipients.

The element can contain multiple [[en:ibmanager:ibmanager-alerts#<Recipient>|<Recipient>]] elements.

The element does not contain any attributes.

=== <Recipient> ===

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

A mandatory element located in the [[en:ibmanager:ibmanager-alerts#<Recipients>|<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.