====== Alerty programu ibmanager ======

Mechanizm alertów zaimplementowany w programie **ibmanager** polega na informowaniu użytkownika **IB-System** o zdefiniowanych zdarzeniach. Jest on oparty na pewnych regułach takich jak kalendarz powiadomień oraz ich częstotliwość. Mechanizm ten jest udostępniony bibliotekom logik i ich autor, nie musi obsługiwać tych reguł, wystarczy że je zdefiniuje w pliku konfiguracyjnym alertów.

Do każdego alertu doklejana jest informacja o aplikacji układu sterowania w postaci: **NazwaAplikacji-NazwaInstancji: tekst alertu**, o ile została ona zdefiniowana w atrybutach **Name** oraz **Instance** elemrntu [[pl:ibmanager:ibmanager-config#<Application>|<Application>]] pliku konfiguracyjnego programu **ibmanager**.

Alerty załączane są przez zdefiniowanie w pliku konfiguracyjnym programu **ibmanager** elementu [[pl:ibmanager:ibmanager-config#<Alerts>|<Alerts>]] oraz jego atrybutu **Path**, wskazujący na plik konfiguracyjny alertów.

Mechanizm alertów programu **ibmanager** jest ściśle związany z programem [[pl:ibalert:start|ibalert]]. Program **ibmanager** łączy się z programem **ibalert** przy pomocy [[pl:ibprotocol:start|ibprotokołu]].

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

===== Przykładowy plik konfiguracyjny alertów =====

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

Głównym elementem pliku konfiguracyjnego jest **Config**, posiadający między innymi atrybut **Version**, będący wersją pliku konfiguracyjnego alertów. Właściwą wersją pliku konfiguracyjnego alertów jest wersja 1.1 (dla programu ibmanager w wersji 3.7.4).

Jeżeli wersja ta nie będzie się zgadzała z numerem wersji aktualnie obsługiwanym przez program, wówczas zostanie zgłoszony błąd i program zakończy działanie. 

Pozostałe elementy pliku konfiguracyjnego alertów zostały opisane w osobnych rozdziałach dokumentacji.

==== <IbAlert> ====

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

Element obowiązkowy odpowiedzialny za konfigurację połączenia z programem [[pl:ibalert:start|ibalert]]. 

Element zawiera atrybuty:

  * **HostName** - nazwa DNS lub adres IP maszyny, na której jest uruchomiony program [[pl:ibalert:start|ibalert]]. 
  * **TcpPort** - numer portu TCP, na którym program [[pl:ibalert:start|ibalert]] nasłuchuje.
  * **CommunicationTimeout** - timeout wyrażony w milisekundach użyty w komunikacji z programem **ibalert**. Jeżeli jakakolwiek operacja sieciowa związana z programem **ibalert** trwa dłużej jak wartość tego atrybutu, wówczas jest ona przerywana i logowany jest błąd.
  * **SecureConnection** - atrybut typu bool, mówi czy serwer [[pl:ibalert:start|ibalert]] będzie wykorzystywał bezpieczną komunikację SSL. Jeżeli tak, wówczas użyje on klucza PEM key.pem, lokalnego certyfikatu ibpakietu (local.cert.pem) oraz lokalnego certyfikatu instytucji certyfikującej (local.ca.cert.pem). Wszystkie te pliki powinny się znajdować w katalogu licencji (Więcej: [[pl:ibmanager:ibmanager-config|plik konfiguracyjny programu ibmanager]]). Zalecana wartość to "true".

==== <Alerts> ====

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

Element obowiązkowy, odpowiedzialny za zdefiniowanie wszystkich alertów, które program **ibmanager** ma obsługiwać.

Element może zawierać wiele elementów [[pl:ibmanager:ibmanager-alerts#<Alert>|<Alert>]].

Element nie zawiera żadnych atrybutów.

=== <Alert> ===

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

Element obowiązkowy znajdujący się w elemencie [[pl:ibmanager:ibmanager-alerts#<Alerts>|<Alerts>]]. Element jest odpowiedzialny za zdefiniowanie pojedynczego alertu, który ma zostać obsłużony (przekazany do aplikacji **ibalert**) przez **ibmanagera**.

Element zawiera atrybuty:

  * **Id** - (obowiązkowy) identyfikator alertu. Identyfikator ten nadany jest w pliku konfiguracyjnym [[pl:ibmanager:ibmanager:logics:start|logiki]].
  * **LogicName** - (obowiązkowy) nazwa logiki, w pliku konfiguracyjnym której zdefiniowano alert o identyfikatorze **Id**.
  * **InstanceName** - (opcjonalny) Jeżeli atrybut nie został zdefiniowany, oznacza to że alert należy do sekcji globalnej logiki. Jeżeli został zdefiniowany, wówczas oznacza on nazwę instancji danej logiki, w której dany alert został zdefiniowany. Jeżeli zdefiniowano **InstanceName** to jego wartość nie może być pusta.

Mając zdefiniowany alert, można mu przypisać konkretne ujście – czyli przeznaczenie wraz z zasadami, jakimi musi się kierować wysyłając dany alert. Ujście zdefiniowane jest przez element [[pl:ibmanager:ibmanager-alerts#<Sink>|<Sink>]]. Jeden alert może mieć wiele ujść lub żadnego – wtedy nie zostanie obsłużony.

== <Sink> ==

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

Element opcjonalny znajdujący się w elemencie [[pl:ibmanager:ibmanager-alerts#<Alert>|<Alert>]]. Element jest odpowiedzialny za zdefiniowanie pojedynczego ujścia dla powiązanego alertu (rodzica).

Element zawiera atrybuty:

  * **RecipientId** - (obowiązkowy) identyfikator odbiorcy. Odbiorcy są zdefiniowani w elemencie [[pl:ibmanager:ibmanager-alerts#<Recipients>|<Recipients>]]. **RecipientId** jest wyszukiwany spośród atrybutów **Id** wszystkich elementów [[pl:ibmanager:ibmanager-alerts#<Recipient>|<Recipient>]]. Jeżeli nie zostanie znaleziony wówczas dane ujście nie zostanie obsłużone i sytuacja taka zostanie zalogowana.
  * **NotificationType** - (obowiązkowy) typ powiadomienia. Może przyjmować wartości:
    * **NM_SMS** - wiadomość SMS. Jeżeli wskazany odbiorca nie ma przypisanego numeru telefonu (nie zdefiniowano atrybutu **Phone** w elemencie [[pl:ibmanager:ibmanager-alerts#<Recipient>|<Recipient>]]) to ujście nie zostanie obsłużone i sytuacja taka zostanie zalogowana.
    * **NM_EMAIL** - wiadomość e-mail. Jeżeli wskazany odbiorca nie ma przypisanego adresu e-mail (nie zdefiniowano atrybutu **Email** w elemencie [[pl:ibmanager:ibmanager-alerts#<Recipient>|<Recipient>]]) to ujście nie zostanie obsłużone i sytuacja taka zostanie zalogowana.
    * **RuleName** - (obowiązkowy) identyfikator zasad wysyłania alertów. Zasady są zdefiniowani w elemencie [[pl:ibmanager:ibmanager-alerts#<Rules>|<Rules>]]. **RuleName** jest wyszukiwany spośród atrybutów **Name** wszystkich elementów [[pl:ibmanager:ibmanager-alerts#<Rule>|<Rule>]]. Jeżeli nie zostanie znaleziona wskazana zasada, wówczas dane ujście nie zostanie obsłużone i sytuacja taka zostanie zalogowana. **RuleName** definiuje zasady, jakimi program **ibmanager** będzie się kierował przekazując dany alert do odbiorcy konkretnego ujścia.

==== <AlertsMatch> ====

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

Element opcjonalny. 

Ręczne definiowanie alertów dla wszystkich szablonów alertów zdefiniowanych w logikach może być uciążliwe, szczególnie jeżeli wszystkie są wykorzystane oraz wszystkie mają być w ten sam sposób obsłużone, dlatego został wprowadzony element określający metodę dopasowywania szablonów alertów z plików konfiguracyjnych logik do alertów w pliku konfiguracyjnym alertów. 

Element zawiera atrybuty:

  * **Mode** - (obowiązkowy) definiuje w jaki sposób ma działać funkcjonalność **AlertsMatch**, może przyjmować wartości:
    * **Exact** - dopasowywanie dokładne. Oznacza że identyfikator alertu, nazwa logiki i nazwa instancji, odczytane z pliku konfiguracyjnego logiki, muszą być identyczne z wartościami atrybutów **Id**, **LogicName** oraz **InstanceName** elementu  [[pl:ibmanager:ibmanager-alerts#<Alert>|<Alert>]] w pliku konfiguracyjnym alertów.
    * **Regex** - dopasowywanie na podstawie wyrażeń regularnych. Oznacza, że atrybuty **Id**, **LogicName** oraz **InstanceName** elementu [[pl:ibmanager:ibmanager-alerts#<Alert>|<Alert>]] w pliku konfiguracyjnym alertów stanowią wyrażenia regularne, na podstawie których parsowane są identyfikator alertu, nazwa logiki i nazwa instancji, odczytane z pliku konfiguracyjnego logiki.
    * **Both** - Użyte są obie metody. Najpierw jest użyta metoda **Exact**. Jeżeli alert nie zostanie znaleziony, wówczas druga próba odbywa się przy użyciu metody **Regex**.

Dla przykładu:

Jeżeli został zdefiniowany alert o identyfikatorze **RelayEnabled** w logice **Thermostat** i zostało zdefiniowanych dziesięć instancji tej logiki, o nazwach "t0", "t1", …, "t9", wówczas zamiast potrzeby definiowania dziesięciu elementów [[pl:ibmanager:ibmanager-alerts#<Alert>|<Alert>]] w pliku konfiguracyjnym alertów i powtarzania za każdym razem tych samych  wartości, różniącymi się jedynie nazwami instancji logik, wystarczy zdefiniować jeden element [[pl:ibmanager:ibmanager-alerts#<Alert>|<Alert>]] :

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

Element **AlertsMatch** jest opcjonalny,  kiedy nie został zdefiniowany, wówczas używana jest metoda **Exact**.

==== <Rules> ====

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

Element obowiązkowy, odpowiedzialny za zdefiniowanie wszystkich zasad dla alertów.

Element może zawierać wiele elementów [[pl:ibmanager:ibmanager-alerts#<Rule>|<Rule>]].

Element nie zawiera żadnych atrybutów.

=== <Rule> ===

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

Element obowiązkowy znajdujący się w elemencie [[pl:ibmanager:ibmanager-alerts#<Rules>|<Rules>]]. Element jest odpowiedzialny za zdefiniowanie pojedynczej zasady dla alertów.

Element zawiera atrybuty:

  * **Name** - (obowiązkowy) identyfikator (nazwa) zasady. Nazwa ta musi być unikatowa w całym zbiorze zdefiniowanych zasad. Jeżeli znaleziony zostanie duplikat, wówczas zostanie to uznane za błąd logiczny – program zakończy działanie z odpowiednim wpisem w logach.
  * **Priority** - priorytet alertu - liczba całkowita bez znaku. Im mniejsza wartość tym wyższy priorytet. Priorytet ten nie jest interpretowany przez program **ibmanager** a jedynie przekazywany do programu **ibalert**.
  * **MinSendInterval** - atrybut określa minimalny okres, co który dany alert może być wysłany do konkretnego ujścia. Czyli alert związany z danym ujściem, nie będzie wysyłany częściej niż wartość tego atrybutu. Atrybut ten jest podany w postaci **HH:MM:SS** gdzie **HH** – oznacza godziny, **MM** – oznacza minuty, **SS** – oznacza sekundy. Jeżeli wystąpiła sytuacja alarmowa w logice, w wyniku czego cały czas szereguje dany alert do wysłania, to mechanizm alertów nie będzie wysyłał alertu do danego ujścia zgodnie z tym, jak dany alert zostaje zgłaszany przez logikę, lecz bierze czas wysłania ostatniego alertu, dodaje do niego **MinSendInterval** i w wyniku uzyskuje czas, w którym dany alert zostanie ponownie wysłany – nie wcześniej, ale może być nawet później – zależy to od harmonogramu tygodniowego zasady opisanego w dalszej części dokumentacji.

Mając zdefiniowaną pojedynczą można zdefiniować harmonogram tygodniowy zasady, który definiuje dni tygodnia oraz godziny, w których dany alert może zostać wysłany do odbiorcy. Harmonogram jest definiowany przez element [[pl:ibmanager:ibmanager-alerts#<ActivePeriod>|<ActivePeriod>]]. Zasada może mieć dowolną ilość takich elementów.

Domyślnie, cały tydzień ma zablokowaną możliwość wysyłania alertów – jeżeli zdefiniowano element **Rule** bez żadnego elementu [[pl:ibmanager:ibmanager-alerts#<ActivePeriod>|<ActivePeriod>]] to alert nigdy nie zostanie wysłany do danego ujścia alertu związanego z tą zasadą). Element **ActivePeriod** aktywuje przedział czasu, w którym alert może zostać wysłany.

**Uwaga:** jeżeli dany alert został choć raz zaszeregowany przez logikę do wysłania, lecz zasady nie pozwalają w chwili obecnej go wysłać, to zostanie on wysłany jeżeli tylko zasady na to pozwolą, nawet jeżeli sytuacja alarmowa przestała obowiązywać i logika przestała zgłaszać alert. Logiki posiadają możliwość "anulowania" wysłania alertu, lecz jest to możliwe wtedy kiedy autor logiki zdecyduje aby skorzystać z takiego mechanizmu. W jednej sytuacji jest to pożądane, w innej nie, dlatego ten wybór leży po stronie autora logiki.

== ActivePeriod ==

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

Element opcjonalny znajdujący się w elemencie [[pl:ibmanager:ibmanager-alerts#<Rule>|<Rule>]]. Element **ActivePeriod** aktywuje przedział czasu dla zasady (element rodzic) , w którym alert może zostać wysłany.

Element zawiera atrybuty:

  * **Day** - (obowiązkowy) identyfikator dnia lub dni tygodnia. Może przyjmować wartości:
    * **Monday** - poniedziałek
    * **Tuesday** - wtorek
    * **Wednesday** - środa
    * **Thursday** - czwartek
    * **Friday** - piątek
    * **Saturday** - sobota
    * **Sunday** - niedziela
    * **Week** - wszystkie dni tygodnia
    * **Weekend** - sobota i niedziela
    * **Weekdays** - dni od poniedziałku do piątku
  * **Start** - (opcjonalny) godzina początku przedziału zezwalającego na wysyłanie alertów w formacie **HH:MM:SS**. Jeżeli nie zdefiniowano tego atrybutu, wówczas jego wartość zostaje ustawiona na **00:00:00**.
  * **Stop** - (opcjonalny) koniec przedziału zezwalającego na wysyłanie alertów w formacie **HH:MM:SS**. Jeżeli nie zdefiniowano tego atrybutu, wówczas jego wartość zostaje ustawiona na **23:59:59**.

==== <Recipients> ====

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

Element obowiązkowy, odpowiedzialny za zdefiniowanie wszystkich odbiorców alertów.

Element może zawierać wiele elementów [[pl:ibmanager:ibmanager-alerts#<Recipient>|<Recipient>]].

Element nie zawiera żadnych atrybutów.

=== <Recipient> ===

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

Element obowiązkowy znajdujący się w elemencie [[pl:ibmanager:ibmanager-alerts#<Recipients>|<Recipients>]]. Element jest odpowiedzialny za zdefiniowanie pojedynczego odbiorcy alertów.

Element zawiera atrybuty:

  * **Id** - (obowiązkowy) identyfikator odbiorcy, musi być unikatowy w całym zbiorze zdefiniowanych odbiorców. Jeżeli znaleziony zostanie duplikat, wówczas zostanie to uznane za błąd logiczny – program zakończy działanie z odpowiednim wpisem w logach.
  * **FirstName** - (obowiązkowy) pierwszy człon nazwy odbiorcy (imię).
  * **LastName** - (opcjonalny) drugi człon nazwy odbiorcy (nazwisko).
  * **Phone** - (opcjonalny) numer telefonu odbiorcy.
  * **Email** - (opcjonalny) adres poczty elektronicznej odbiorcy (e-mail).