i4connected Knowledgebase 5.6

The Email Adapter

Abstract

Learn more about the i4connected Email Adapter used to provide a way for physical devices to send alarms using the i4connected Event flow.

Unlike the other i4connected Adapters, the purpose of the Email Adapter is to process configured Email data from a predefined mail server, using email protocols like IMAP, POP3 and Exchange.

The handling flow of the Email Adapter is based on a set of inbound and outbound operations, as follows:

  • The i4connected Email Adapter connects to the configured Email account and reads the received Emails.

  • The i4connected Email parser Device validates all the received Emails and consequently generates i4connected Events.

    The Email parser Device has the ability to match Email contents with a set of optional parser filters (Sender Name Pattern, Sender Address Pattern, Recipient Name Pattern, Recipient Address Pattern, Subject Pattern and Body Pattern). Using the filters ensures that only a subset of the emails will be parsed by a certain Email parser Device.

    Depending on the matching process results, several outcomes can be distinguished.

    1. If the matching process is successful, the Email is further on handled by the dedicated parsing script. The dedicated script will return all the needed information for generating events based on the parsed email. An important information that should be parsed is the target device name. When the target device does not exist in the i4connected system, it will be created. As a final result, an Event is generated, having the Event source set to the target device.

      The Extra Information area in the Event Occurrence details view panel shows the Email metadata, such as: Sender name and address, Recipient(s) name and address, Email subject, Email body and other useful information.

      Note

      The name of the target device is generated on basis of the script defined rule, which by default is "{siteName} - {deviceName}".

    2. If the matching process is successful, but the parsed result does not contain all the needed information, to generate the event (e.g. Site name is missing), an Event is generated, having the Event source set to the parser device.

      The user can easily identify the Event mismatch reason, by opening the Event occurrence in detailed view mode and checking the Extra Information area. The list below consists of all the potential mismatch reasons that can occur for an event having the name "The email occurrences could not be parsed":

      1. "Missing script error."

      2. "Script returned null."

      3. "Script didn't return any alarm."

      4. "Device name not found in email."

      5. "Alarm name not found in email."

      6. "Cannot create device without a valid site name."

      7. "Site not found in the system."

      8. "Error creating device '<parsed device name>'."

      9. "Target device not found in the system."

      10. "Target device is not active."

      11. "Unexpected error."

      12. and other exceptions related to Email contents validated against the parsing script.

    3. If the matching process fails, meaning that no Email parser Device was configured with some patterns to match the email data, an Event is generated, having the Event source set to the Email Adapter communicating with the mailbox.   The name of the generated event is "The format of the email was not recognized" and the additional information in the event metadata will contain the specific reason "There was no email adapter device configured to match the received email."

      Warning

      Spam emails will also be picked up by the i4connected Email Adapter and, most probably, there will be no email parser devices configured to handle such emails, so this event will be generated.

    4. If an email without body is received, an Event is generated, having the Event source set to the Email Adapter communicating with the mailbox. The name of the generated event is "The format of the email was not recognized" and the additional information in the event metadata will contain the specific reason "The email does not have a text body."

Email adapter connection
Abstract

Check out this article and learn how to establish the connection between your mailbox and i4connected, by means of Email adapters.

The connection between the i4connected server and an Email server, is established by means of an Email adapter.

The list of already available Email adapters can be accessed by all the users having at least the View adapters permission enabled, by clicking the Email adapter name selector, in the Add / Edit Email Device panel.

Select_Email_adapter_name.jpg

The Email adapter name selector

In this view, all the already configured Email adapters are listed. The user can select an Adapter from the list and apply it to the Email parser device, update them or remove them.

Note

Only users having the Manage adapters permission enabled can add and edit Adapters.

Select_email_server_list.jpg

The Select Email server panel

Additionally, the user can click the Add toolbar button to start configuring a new Email server

Add_button.jpg

The Add button

The Add email server panel features the following settings:

Add_email_server.jpg

The Add Email server panel

  • Name - specifies the name of the Email server.

  • Description - the user friendly description of the Email adapter.

  • Poll interval(ms) - the data synchronization time interval, expressed in milliseconds (the default is 60000 – 1 minute).

  • Max messages - sets the amount of messages read per polling cycle.

  • Site time zone metadata field - the name of the Site metadata, representing the time zone of the respective site.

    If no Site time zone metadata is defined or if the defined one is not found, the Adapter time zone will be, by default, parsed.

    Note

    The Site time zone metadata needs to be defined by the system administrator, using the "Enumeration" type when adding the Custom field definition.

    The list of enumeration values will be represented by a list of all valid time zones, available in the i4connected database.

    CDF.jpg

    The Add Custom field definitions panel

    For more details about management of Custom field definitions, please also visit the dedicated article here. Further on, management of Site metadata is described by this article here.

  • Error Event type - allows the user with possibility to set the Event type, for the generated alarms. The Event type can be selected by clicking the dedicated selector. The list of Event types will be opened alongside, allowing the user to chose the desired Event type.

    EVent_types_selector.jpg

    Note

    By defining the Error Event type, the user can easily identify the generated online alarms and historical alarms, in the dedicated panels, by applying the respective filter.

    For more details on events filtering option, please also visit the dedicated article here.

  • Protocol - sets the communication protocol, allowing the user to chose from the following drop-down list items:

    protocol_drop-down.jpg

    The Email Adapter protocols

    • POP3 - The Post Office Protocol 3 is a standard protocol for receiving e-mails on a single device.

      If the POP3 protocol is selected, the user is required to fill in the following account settings:

      Ad_POP3_adapter.jpg
      • User name - specifies the user name of the POP3 Email server account.

      • Password - specifies the password used to access the POP3 Email server account.

      • Host - specifies the Email hosting service in which the email messages and associated files are stored on the server (e.g. pop.gmail.com).

      • Port - specifies the communication port of the POP3 Email server account (e.g. 995, when using SSL)

      • Use SSL - when set to true, the secure socket layer will be enabled (recommended).

    • IMAP - The Internet Message Access Protocol (IMAP) is a mail protocol used for accessing emails on a remote web server from a local client.

      If the IMAP protocol is selected, the user is required to fill in the following account settings:

      Add_IMAP_adapter.jpg
      • User name - specifies the user name of the IMAP Email server account.

      • Password - specifies the password used to access the IMAP Email server account.

      • Host - specifies the Email hosting service in which the email messages and associated files are stored on the server (e.g. imap.gmail.com).

      • Port - specifies the communication port of the IMAP Email server account (e.g. 993, when using SSL)

      • Use SSL - when set to true, the secure socket layer will be enabled (recommended).

    • Exchange - Microsoft Exchange, also known as Microsoft Exchange Server, is a type of account that can be added to an Email application.

      Note

      Exchange Web Services can be enabled and accessed using the OAuth authentication service provided by Azure Active Directory.

      For more details on how to authenticate an EWS application, using OAuth please also visit this article here.

      When selected as communication protocol for the i4connected Email Adapter, the user is required to fill in the following settings:

      Add_Exchange_Adaapter.jpg
      • Exchange App Id - specifies the OAuth application ID issued by Azure Active Directory.

      • Exchange Tenant Id - specifies the identification number of the application tenant.

      • Exchange Client Secret - specifies the application secret attributed to the OAuth application at the app registration step.

      • Exchange Url - The url of the application, where authentication responses can be sent and received by the app.

      • Exchange Mail Box - the address of the target Email account.

  • Select owner - name of the Adapter owner.

    IoT_owner.jpg

    Adapter owner selector

    By clicking on the owner selector, the Select Users panel is opened allowing the user to chose the Adapter's owner.

    List_of_users.jpg

    Select Users panel

    Important

    When adding a new Adapter the creator user is by default set as Adapter's owner. However, the owner can be changed after the Adapter was saved, by all users having at least the Manage adapters permission enabled.

  • Time zone - The time zone used by the new Email Adapter. By default, the Time zone is predefined for the currently logged in user.

    Note

    By default, the generated Email alarms consider the Time zone selected at this field, if no Site time zone metadata field is defined.

  • Trace Level - trace levels determine which events the trace provider generates. The user can select the desired trace level from a drop-down list where the following predefined values are available: Trace, Debug, Info, Warn, Error, Fatal and Off.

  • Enabled / Disabled toggle button - If the setting is turned on, the Adapter is enabled and functional.

Email Alarm Script
Abstract

Check out this article and learn more details about the Email Alarm scripts and how you can manage them for the Email Adapter.

The core functionality when processing Email data, is the Email Alarm Script. Emails that have successfully passed the matching process, enforced by the parser filters are sent to the Alarm Script, selected by the user in the Add / Edit Device panel.

Select_script_button.jpg

The Script selector

By clicking the Script selector, the Email Alarm scrips panel is opened, displaying all the existing scripts.

Note

The Email Alarm scripts list is accessible to all users having at least the Manage devices permission enabled.

By default, the Email Alarm scripts list is populated with eight script snippets, that the user can apply as they are, or customize them.

The default script snippets are:

  • Advitornic

  • Carel

  • Carel2

  • Danfoss

  • Dixell

  • Dixell2

  • Eliwell

  • Wurm

Users having higher authority permission level can also manage Email Alarm scripts, as follows:

Email_Alarm_scripts_list_updated.jpg

The Email Alarms scrips panel

Note

The Email Alarm scripts can be managed by all users having at least the Manage email event scripts permission enabled.

Editing and testing scripts

Users having the Manage email event scripts permission enabled can open a listed script in edit mode, by clicking the Edit button.

Script_opened.jpg

The Edit Alarm Email script panel

The Edit Alarm Email script panel is structured into multiple tabs, where the user can write the script, test it, check the obtained results and read log messages, as follows:

The Script tab

When opening the Edit Alarm Email Script panel, the Script tab is by default opened.

Script_tabe.jpg

The Script tab

In this view, the fully customizable email script snippet is displayed, written in C# programming language.

  • Script - the script snippet acting as an email parser.

    Tip

    Unlike the Event script list expressions, that can also use simple online calculations, the Alarm Email script is based on a multi-line C# structure, enclosed between curly brackets {} and requiring a return function.

    The "return" statement terminates execution of the script and determines the generation of event occurrences, log messages, etc.

    Even though C# is a high-level language, it is relatively easy to read. However, when it comes to editing the default Email script snippets, it is recommended that the user has, at least, basic programming knowledge.

  • Description - the script description that will be displayed in all its applicable contexts.

In order to preserve any changes done in this tab the user is required to click the Save button at the bottom of the panel.

The Test Script tab

The Test Script tab allows the user to check the script against a simulated email by providing the email elements Sender Name, Sender Address, Recipient Name, Recipient Address and Subject.

Test_script_updated.jpg

The Test Script tab

In this view, the user can insert either a Text body or an Html body. Both fields allow the user with possibility to simulate the emailing process, by clicking the Test button Test_button.jpg.

The simulation process is initiated in background and test outcome is displayed under the Results tab, which is automatically opened displaying more details about the operation.

The Results tab

The Results tab is usually opened automatically after triggering a test, under the Script Test tab.

In this view, the content of the simulated Alarm is displayed, allowing the user to see how the final result will look like or if the script was correctly configured.

Results_tab.jpg

The Results tab

Note

The Results tab provides the user with information only when it is opened after triggering a script test.

By clicking the Show object button, the View Metadata panel is opened, allowing the user to read more information about the simulated alarm metadata.

View_metadata_panel.jpg

The View Metadata panel

In case there are issues with the script, the Results tab provides the user with more information about the failure reason.

General_error_message.jpg

Example of a script general error message

The Log Messages tab

The purpose of the Log Messages tab is to provide the user with additional support in validating the Email script snippet. It serves as a debug console, allowing the user to add messages in order to help creating a valid script.

Log_messages_tab.jpg

The Log Messages tab

The Log Messages tab is always available, in the Edit Alarm Email script panel, but the user can freely decide when to use it, by adding or removing script lines that output log messaged.

Deleting redundant scripts

The Edit Alarm Email Script panel provides the user with the possibility to remove a script, by clicking the Delete toolbar button. In the Delete snippet panel the user is requested to manually fill in the deletion confirmation code. To proceed with the deletion operation the user can click the Delete button.

Delete_snippet.jpg

The Delete snippet panel

Adding new scripts

Users having the Manage email event scripts permission enabled can create new Alarm Email scripts, by clicking the Add toolbar button available in the Email Alarm scripts.

Add_script_button.jpg

The Add script button

The Add Alarm Email Script panel is also split up into four tabs, each being dedicated to a specific task:

Add_Alarm_Email_Script_panel.jpg

The Add Alarm Email Script panel

  • Under the Script tab, the user can start writing the Script that will be used to parse Emails and generated Alarms.

    Warning

    As already indicated, the Script field expects a C# type script.

    To preserve the written script, the user needs to click the Save button located at the bottom of the panel.

  • The Test Script tab is dedicated to validating the written script, against a set of parser filters.

  • The Results tab displays the tested results, providing the user with the chance to check if the script works as expected, before saving and using it.

  • The Log Messages tab displays the logs registered during the script testing phase.

Email Events handling
Abstract

Check out this article and learn more details about the handling of i4connected alarms generated by the Email Adapter.

Events generated by the Email script parser can be managed in the Online Alarms panel, providing the user with the same functions available for all i4connected Events, such as close, acknowledge, take ownership, assign ownership, prioritize and comment.

Tip

For more details about Online Alarms management, please also visit the dedicated article here.

As described at the beginning of this article, the Email account configured for the Email Adapter is periodically checked for new Emails. Each new Email is consequently matched with a set of filter patterns. Depending on the results of this matching process, an Event is generated and made available in the Online Alarms panel.

Listed Email Events can be opened in detailed view mode, by all users having at least the View events permission enabled.

Tip

For more details about the Event Occurrences panel, please also visit the dedicated article here.

When opening an Email Event occurrence in detailed view mode, besides the event sources (Device / Adapter / Site) the user can also access the Email Alarm Scripts list, by clicking the Script selector. Users having the Manage event scripts permission enabled can edit and test Email scripts, as described by the dedicated article.

Script_selector.jpg

The Script selector

The Extra Information area of Email Event occurrences provides the user with more details about the Event.

Example_of_ExtraInfo_for_alarm.jpg

The Extra Information area for a successful Email Event occurrence

If the Event occurred as a result of a parsing error, the user can get information about the reason for failure under the Extra Information area.

Tip

For more details about possible mismatch and failure reasons, please also read the overview article.

Reason_for_failure.jpg

The Extra Information area for a failed Email Event occurrence