Difference between revisions of "Notifications Utility"

From HSYCO
Jump to navigation Jump to search
(Created page with " == Conditions == border|500px border|500px File:plugin_notifi_utility_con...")
 
m
 
(22 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
This plugin provides an application for monitoring and configuring notifications for installations comprising heterogeneous sensors and I/O devices managed by several users possibly divided into groups.
 +
 +
The application allows for the specification of alarm conditions with different levels, generates logs and notifies users via e-mail and/or SMS text messages.
 +
 +
Before using the plugin, configure all the I/O Servers needed and make sure they all communicate correctly with HSYCO.
 +
 +
To view the Notifications Utility interface go to the URL of the "notif" project on your server; for instance <nowiki>https://192.168.0.50/hsycoserver/notif</nowiki>.
 +
 +
The application is divided in the following sections:
 +
 +
== Groups ==
 +
A group represents a set of users that should receive the same notifications.
 +
 +
[[File:plugin_notifi_utility_groups.png|border|500px]]
 +
 +
 +
Create/delete groups using the '''+'''/'''-''' buttons at the bottom of the list and enter a name.
 +
 +
For each group you can select the days it is active and, for each day, up to 2 time intervals in which it is active. When a group is active, the users belonging to the group will receive alarm notifications targeted for such group. You can also enable/disable a group for a certain period of time.
 +
 +
Currently active groups display a "•" symbol next to their names.
 +
 +
== Users ==
 +
[[File:plugin_notifi_utility_users.png|border|500px]]
 +
 +
Create/delete users using the '''+'''/'''-''' buttons at the bottom of the list and enter a name.
 +
 +
*'''E-Mail''': if specified, alarms notifications for the user will be sent to the specified address
 +
*'''E-mail fields''': if default is selected, e-mail body message will contain 1) date/time 2) alarm message 3) datapoint value 4) alarm condition level. If custom is selected, e-mail body elements become selectable (except from alarm message that will be always present)
 +
*'''Tel.''': if HSYCO is provided with a [[GSM | GSM I/O Server]] you can specify the phone number of the user that will be used to send SMS text notifications to. Use the same number format described in the GSM I/O Server documentation
 +
*'''Group(s)''': select the group(s) the user belongs to
  
 
== Conditions ==
 
== Conditions ==
 +
This section is where you define the datapoints to be monitored by the application and specify the conditions that will trigger a notification.
 +
 +
A datapoint can be either an I/O Served datapoint or a system variable.
 +
 +
To add a datapoint click on the '''+''' button at the bottom of the list and specify the datapoint ID and a descriptive name.
 +
 
[[File:plugin_notifi_utility_conditions_add_dp.png|border|500px]]
 
[[File:plugin_notifi_utility_conditions_add_dp.png|border|500px]]
 +
 +
To add an I/O Server datapoint just specify its ID, for variables use the upper-case name prefixed by '$'.
 +
 +
After you added a datapoint you can optionally specify a unit of measure and upper/lower boundaries for its value to discard error values. You can also enable/disable a datapoint for a certain period of time: beside the flag "Enabled" you can set the time after which the datapoint will change its status (from enabled to disabled and viceversa).
 +
 
[[File:plugin_notifi_utility_conditions.png|border|500px]]
 
[[File:plugin_notifi_utility_conditions.png|border|500px]]
 +
 +
Then you can add notification conditions:
 +
 
[[File:plugin_notifi_utility_conditions_add_notif.png|border|500px]]
 
[[File:plugin_notifi_utility_conditions_add_notif.png|border|500px]]
  
−
== Groups ==
+
* '''Condition''': select among the available comparisons, i.e. equals (=), different from (!), lower than (<) or greater than (>) and enter the reference value
−
[[File:plugin_notifi_utility_groups.png|border|500px]]
+
* '''Groups''': select the groups the notification is targeted to
 +
* '''Message''': enter the notification message. You can use the "$val" placeholder that will be replaced with the value that triggered the notification
 +
* To avoid repeated notifications you can specify a time interval after an alarm condition is exited in which new notifications will be suppressed
 +
* '''Level''': select the level of the condition. The level "Log only" will cause the condition to be added to the log when occurring, but no alarm will be displayed and no notification will be sent. The other levels are customisable and must be specified in the file "notifications_utility/config/levels.ini" as follows.
 +
: Add a single line listing the levels values (1 ... N) and the corresponding names. Here is a valid configuration:
 +
: <pre>1=warning; 2=danger; 3=system</pre>
  
−
== Users ==
+
Datapoints for which alarm conditions have been defined show a "•" symbol next to their names in the list. If one of the conditions is active, both the condition and the device name turn red.
−
[[File:plugin_notifi_utility_users.png|border|500px]]
 
  
 
== Alarms ==
 
== Alarms ==
 
[[File:plugin_notifi_utility_alarms.png|border|500px]]
 
[[File:plugin_notifi_utility_alarms.png|border|500px]]
 +
 +
The main page of the application shows the ongoing alarms.
 +
 +
When an alarm condition occurs, it is listed in this table and its message will be displayed in red. To acknowledge the alarm click on the entry, you'll be prompted to confirm the reset, optionally adding a note.
 +
 +
If the alarm has been acknowledged, but the condition that triggered it is still persisting, then its message will turn yellow, otherwise it will be removed from the list.
  
 
== Log ==
 
== Log ==
 
[[File:plugin_notifi_utility_log.png|border|500px]]
 
[[File:plugin_notifi_utility_log.png|border|500px]]
 +
 +
This page lets you browse and filter the log database.
 +
 +
The database contains alarm events and reset actions (and optional notes) on alarm notifications.
 +
 +
To perform a search specify a date range and, optionally, the other filter options and click on '''Refresh'''. The result of the query can be sent via e-mail in CSV format clicking on the envelop icon.
 +
 +
== Advanced functionalities ==
 +
 +
=== Events ===
 +
The application generates USER events that can be used to add custom logic to alarm events.
 +
 +
Whenever a new notification is created, the following USER event is triggered:
 +
 +
<pre>
 +
alarm.new = <notification_message>
 +
</pre>
 +
 +
For each datapoint with alarm conditions defined, the following USER events are triggered:
 +
 +
<pre>
 +
alarm.<datapoint_id> = 1      // when at least an alarm condition on the datapoint is true
 +
alarm.<datapoint_id> = 0      // when all alarm conditions on the datapoint are false
 +
</pre>
 +
 +
=== Custom alarms lists ===
 +
You can add the alarms list shown in the Alarms page in any page of any other project of yours. Moreover you can have separate lists showing only the alarms for a specific group.
 +
 +
To have a list showing all the alarms you can copy it from the plugin project and paste it to your own project.
 +
 +
To have a list showing only the alarms of a specific group, copy the aforementioned list and append the ID of the group to the list's ID and Name adding a '.' as separation:
 +
 +
<pre>
 +
ntfutil.alarm.list.<group_id>
 +
</pre>
 +
 +
You can find the group IDs in the file ''notifications_utility/config/groups.ini''.
 +
 +
=== Options ===
 +
The file ''notifications_utility/config/config.ini'' can be used to set the following options:
 +
 +
* '''mail_sender''': set the email address used as the sender of email notifications. Defaults to "alarm@hsyco.com"
 +
* '''group_lists''': if custom alarms lists separated by groups are not used, set this option to false to avoid unneeded uisets
 +
* '''startup_notifications''': this option defines whether or not notifications are sent upon the first update of a datapoint's value. Datapoints are initialized at startup and, if high availability is configured, whener the server becomes active. To avoid sending notifications which have possibly already been sent, set this option to false; to make sure no notification is missed between restarts or failover switchings, set it to true (default value).
 +
 +
Example:
 +
 +
<pre>
 +
mail_sender=hello@example.com
 +
startup_notifications=false
 +
group_lists=true
 +
</pre>

Latest revision as of 17:14, 9 March 2021

This plugin provides an application for monitoring and configuring notifications for installations comprising heterogeneous sensors and I/O devices managed by several users possibly divided into groups.

The application allows for the specification of alarm conditions with different levels, generates logs and notifies users via e-mail and/or SMS text messages.

Before using the plugin, configure all the I/O Servers needed and make sure they all communicate correctly with HSYCO.

To view the Notifications Utility interface go to the URL of the "notif" project on your server; for instance https://192.168.0.50/hsycoserver/notif.

The application is divided in the following sections:

Groups

A group represents a set of users that should receive the same notifications.

Plugin notifi utility groups.png


Create/delete groups using the +/- buttons at the bottom of the list and enter a name.

For each group you can select the days it is active and, for each day, up to 2 time intervals in which it is active. When a group is active, the users belonging to the group will receive alarm notifications targeted for such group. You can also enable/disable a group for a certain period of time.

Currently active groups display a "•" symbol next to their names.

Users

Plugin notifi utility users.png

Create/delete users using the +/- buttons at the bottom of the list and enter a name.

  • E-Mail: if specified, alarms notifications for the user will be sent to the specified address
  • E-mail fields: if default is selected, e-mail body message will contain 1) date/time 2) alarm message 3) datapoint value 4) alarm condition level. If custom is selected, e-mail body elements become selectable (except from alarm message that will be always present)
  • Tel.: if HSYCO is provided with a GSM I/O Server you can specify the phone number of the user that will be used to send SMS text notifications to. Use the same number format described in the GSM I/O Server documentation
  • Group(s): select the group(s) the user belongs to

Conditions

This section is where you define the datapoints to be monitored by the application and specify the conditions that will trigger a notification.

A datapoint can be either an I/O Served datapoint or a system variable.

To add a datapoint click on the + button at the bottom of the list and specify the datapoint ID and a descriptive name.

Plugin notifi utility conditions add dp.png

To add an I/O Server datapoint just specify its ID, for variables use the upper-case name prefixed by '$'.

After you added a datapoint you can optionally specify a unit of measure and upper/lower boundaries for its value to discard error values. You can also enable/disable a datapoint for a certain period of time: beside the flag "Enabled" you can set the time after which the datapoint will change its status (from enabled to disabled and viceversa).

Plugin notifi utility conditions.png

Then you can add notification conditions:

Plugin notifi utility conditions add notif.png

  • Condition: select among the available comparisons, i.e. equals (=), different from (!), lower than (<) or greater than (>) and enter the reference value
  • Groups: select the groups the notification is targeted to
  • Message: enter the notification message. You can use the "$val" placeholder that will be replaced with the value that triggered the notification
  • To avoid repeated notifications you can specify a time interval after an alarm condition is exited in which new notifications will be suppressed
  • Level: select the level of the condition. The level "Log only" will cause the condition to be added to the log when occurring, but no alarm will be displayed and no notification will be sent. The other levels are customisable and must be specified in the file "notifications_utility/config/levels.ini" as follows.
Add a single line listing the levels values (1 ... N) and the corresponding names. Here is a valid configuration:
1=warning; 2=danger; 3=system

Datapoints for which alarm conditions have been defined show a "•" symbol next to their names in the list. If one of the conditions is active, both the condition and the device name turn red.

Alarms

Plugin notifi utility alarms.png

The main page of the application shows the ongoing alarms.

When an alarm condition occurs, it is listed in this table and its message will be displayed in red. To acknowledge the alarm click on the entry, you'll be prompted to confirm the reset, optionally adding a note.

If the alarm has been acknowledged, but the condition that triggered it is still persisting, then its message will turn yellow, otherwise it will be removed from the list.

Log

Plugin notifi utility log.png

This page lets you browse and filter the log database.

The database contains alarm events and reset actions (and optional notes) on alarm notifications.

To perform a search specify a date range and, optionally, the other filter options and click on Refresh. The result of the query can be sent via e-mail in CSV format clicking on the envelop icon.

Advanced functionalities

Events

The application generates USER events that can be used to add custom logic to alarm events.

Whenever a new notification is created, the following USER event is triggered: 

alarm.new = <notification_message>

For each datapoint with alarm conditions defined, the following USER events are triggered: 

alarm.<datapoint_id> = 1       // when at least an alarm condition on the datapoint is true
alarm.<datapoint_id> = 0       // when all alarm conditions on the datapoint are false

Custom alarms lists

You can add the alarms list shown in the Alarms page in any page of any other project of yours. Moreover you can have separate lists showing only the alarms for a specific group.

To have a list showing all the alarms you can copy it from the plugin project and paste it to your own project.

To have a list showing only the alarms of a specific group, copy the aforementioned list and append the ID of the group to the list's ID and Name adding a '.' as separation: 

ntfutil.alarm.list.<group_id>

You can find the group IDs in the file notifications_utility/config/groups.ini.

Options

The file notifications_utility/config/config.ini can be used to set the following options:

  • mail_sender: set the email address used as the sender of email notifications. Defaults to "alarm@hsyco.com"
  • group_lists: if custom alarms lists separated by groups are not used, set this option to false to avoid unneeded uisets
  • startup_notifications: this option defines whether or not notifications are sent upon the first update of a datapoint's value. Datapoints are initialized at startup and, if high availability is configured, whener the server becomes active. To avoid sending notifications which have possibly already been sent, set this option to false; to make sure no notification is missed between restarts or failover switchings, set it to true (default value).

Example: 

mail_sender=hello@example.com
startup_notifications=false
group_lists=true
Retrieved from "https://wiki.hsyco.com/3.8/index.php?title=Notifications_Utility&oldid=9737"