Integrating investigation-based alerts (classic)
Overview
In this section, learn about the notifications generated by investigation-based alerts to integrate them with other systems.
Investigation-based alerts return a set of objects matching the specified conditions either immediately or periodically, sending the result via email or, in the case of global alerts, optionally via the system log.
Create and configure an investigation-based alert using the Finder. The account used to create the alert has an influence on the mechanisms to notify it. If the account is properly configured with a valid email address, alerts associated with that account will send emails to the configured address. In addition to the configured email address, you may specify other recipients of the alert email in the dedicated space. If no email address has been configured for that particular account, at least one recipient has to be manually specified in the dedicated space.
Only those users with the appropriate profile setting (Allow system configuration) can create global alerts. Global alerts can be sent via email, as described above, and optionally via the system log.
Email integration of investigation-based alerts
Email is a proven, ubiquitous, and mature technology, and thus a suitable means to integrate alert info into third-party software. Email is also easy to automate since many programming languages have libraries available to send and receive an email by means of standard email protocols such as SMTP, IMAP, or POP.
Investigation-based alerts are sent via email in HTML form, using the UTF-8 charset and base64 transfer encoding. The subject of the message consists of the word Nexthink followed by a colon and then the name of the alert. The message content is composed of two HTML tables preceded by an embedded CSS snippet which defines the style of the two tables. The first HTML table displays some general information about the alert, whereas the second HTML table holds the result of the investigation associated with the alert, in the case of investigation-based alerts. If an investigation-based alert fails to execute, a message indicating the reason for the failure appears in the place of the results of the corresponding investigation.
In addition to the HTML table with the results of the investigation, the email of an investigation-based alert includes an attachment particularly well suited for integration. This is a compressed Comma Separated Values (CSV) file that holds the same results shown by the HTML, but in plain text. CSV files are understood by a great number of different tools and they are very easy to parse programmatically.
HTML info table
The HTML info table is composed of five fields that give general information about the context of the alert:
Source: name of the Engine that generated the alert.
User: name of the Finder account associated with the alert.
Name: the name of the alert itself.
Description: a brief description of the alert, as displayed in the Finder.
Time or Period: For non-periodic (system or immediate) alerts, the time at which the alert was triggered is shown. In the case of periodic alerts, the period for which the alert was computed is displayed. In both cases, the time of the day or interval of time is expressed in the timezone of the associated user. The name of the timezone is displayed right after the corresponding time or period.
HTML results table
The results of an investigation-based alert are displayed in the form of an HTML table whose first row holds the names of the fields that were selected during the configuration of the alert. Up to a maximum of fifteen fields will be displayed in an email of an alert. If more than fifteen fields were selected when editing the investigation associated with the alert, only the first fifteen will appear in the email and the rest will be discarded. The CSS included in the mail makes the first row of the HTML results table to be highlighted, so the names of the selected fields appear as the headers of each column. Each subsequent row holds the values of the fields for every alerted object, that is, each row shows information about an object which met the conditions specified by the alert. The maximum number of alerted objects which can be displayed in the email of an investigation-based alert is 250 objects. Therefore, an HTML results table may have a maximum of 251 rows, including the first row with the names of the fields. If more than 250 objects are alerted, a brief warning at the end of the email indicates that only partial results are shown.
Compressed CSV attachment
Although it is possible to parse the HTML results table for integrating its data into external software, the HTML tables of Nexthink alerts were mostly designed to be read by human beings. In addition to the HTML results table, however, the email sent by investigation-based alerts includes a compressed text attachment which is much more interesting for integration purposes. The attachment is a CSV file compressed with the well-known Lempel-Ziv LZ77 algorithm whose name is always set to be "alert.zip". When uncompressed, the name of the file becomes "alert.csv". This attachment holds the same data as the HTML results table, with the advantage that its contents are easier to parse.
Once the attachment is uncompressed, the resulting CSV can be easily imported into third-party tools such as your favorite spreadsheet program.
RELATED TASKS