Email Module

The Email Module sends an email to specified recipients whenever its Trigger input is pulsed. This module is only available in the VIP.

Module icon

Overview

You can connect the Trigger input to any module that produces a pulse output. You can use modules that monitor alarm conditions such as changes in status and communication-loss alarms.

For example, if the Trigger input is connected to the output of a Setpoint Module, the Email Module will send an email when the setpoint condition occurs.

The Email Module requires access to an SMTP Server and the credentials required to send messages.

Inputs

Source

These optional inputs allow information such as value and/or source name to be included in the email subject or email message body.

Enable

This input enables or disables the email. If the module is disabled, the Notification Wait Time Left value is set to not available, and the module stops processing Trigger inputs. This input is optional; if you leave it unlinked, the module is enabled by default.

Trigger

When the Trigger input receives a pulse, an email is sent using the parameters defined in the module’s setup registers. The Trigger input should be directly linked to the pulse output register of the ION module that is monitoring the desired trigger condition.

Immediately after a Trigger pulse is received, the current values held at the Source inputs are saved and utilized in the Subject and Message (email body) if the %V1- %V16 and/or %N1-%N16 are specified in their text content.

If the Notification Wait Time Left setup register has been configured to a non-zero value, additional pulses received on the Trigger input after the initial trigger, are aggregated for summary notification as per the Notification Option register.

Cancel

When this optional input is linked, it can be used in conjunction with the Notification Wait Period register to implement notification flooding prevention functionality. For example, if Notification Wait Period is set to a non-zero value to delay the delivery of a given email, then the Cancel input can be linked to the success output of another Email Module (or other pulse output) to potentially cancel the delivery.

Setup registers

From

Specify either the originator's display name (for example, John Doe<jdoe@companyname.com>), or the originator's email address (for example, jdoe@companyname.com).

To, Cc, Bcc

This register holds the comma delimited list of email addresses for the message.

SMTP Server Host

This register holds the SMTP server host name or IP address.

Credential User Name

This register holds the optional user name if the SMTP server host requires authentication. Note that the Virtual Processor configuration file needs to be protected by file security if plain text values are used.

Credential Password

This register holds the optional password if the SMTP server host requires authentication. Note that the Virtual Processor configuration file needs to be protected by file security if plain text values are used.

NOTE: The Credential Password is a plain text password. Click Encryption in the configuration dialog in Designer and click Yes on the message dialog to encrypt the Credential Password and to protect the Virtual Processor configuration file. Click No to cancel the encryption and to close the message dialog.

Enable SSL

This register enables SSL if required by the SMTP Server Host.

Subject

This register holds the text to be used in the email subject.

Placeholders can be used in the subject text and will be replaced with the value and source linked to the respective Source input at the time of the pulse on the Trigger input:

• %N1-%N16: source linked to Source input 1-16, respectively.
• %V1- %V16: value of source linked to Source input 1-16, respectively.
• %T: timestamp when the Trigger input was pulsed.

Message

This register holds the text to be used in the email message body.

Placeholders can be used in the message text and will be replaced with the value and source linked to the respective Source input at the time of the pulse on the Trigger input:

• %N1-%N16: source linked to Source input 1-16, respectively.
• %V1- %V16: value of source linked to Source input 1-16, respectively.
• %T: timestamp when the Trigger input was pulsed.

For example, assume the string in the Message register is set to: Alert %N1 Vln a = %V1; Vln b = %V2; Vln c = %V3; Vln avg = %V4 at %T

The Email module is linked to outputs from the Power Meter module of a device called ‘TEST.PowerMeter’ and the values of those registers when the Trigger input is pulsed are as follows:

Email module Source input	Linked output from Power Meter module	Value when Trigger is pulsed on 7/21/2017 at 2:14:15.426 PM
Source 1	Vln a	120.03
Source 2	Vln b	119.93
Source 3	Vln c	119.90
Source 4	Vln avg	119.96

This scenario results in an outgoing message that looks like this: Alert TEST.PowerMeter Vln a=120.03; TEST.PowerMeter Vln b=119.93; TEST.PowerMeter Vln c=119.90; TEST.PowerMeter Vln avg =119.96 at 7/21/2017 2:14:15.426 PM

HTML Template File

This register holds the full path to an HTML template file that can be used in lieu of the Message register.

If you need to tailor an HTML template for a given instance with customizable strings, use the External String module to store customer names, locations, or other text represented in the template as %V1-%V16.

For a timestamp, %T will insert the trigger time in local time.

For a summary of received triggers when Notification Wait Period is non-zero (see below), use %S in the HTML template to produce a summary of all received triggers during that period.

If you want to reference a logo in your HTML template, use the nomenclature: src=cid:id1 (in this example, id1 refers to the first attachment which needs to be the desired graphics file). The desired graphic needs to be specified in the Attachment setup register.

NOTE: It is strongly recommended that you use %VIPDIR% as a shortcut to the Virtual Processor configuration directory. For example, %VIPDIR%\html.html. Using %VIPDIR% ensures that the configuration is kept together for system backups.

Attachment

This register holds a semi-colon delimited string of the full path to a file attachment to be associated with the email. It can be used to deliver reports on a scheduled basis, to link to relevant web pages or to standard operating procedures associated with a given alarm.

NOTE: It is strongly recommended that you use %VIPDIR% as a shortcut to the Virtual Processor configuration directory. For example, %VIPDIR%\logo.gif. Using %VIPDIR% ensures that the configuration is kept together for system backups.

Use the wildcard “*” to attach all files in a folder. For example, c:\reports\* attaches all of the files in the reports folder.

Retries

This register defines the number of times the Email module tries to contact the SMTP Server Host after previous unsuccessful attempts.

SMTP Service Port

This register defines the TCP port used by the SMTP Server Host.

SMTP Timeout in Seconds

This register defines the amount of time in seconds that the Email module waits before timing out on the SMTP Server Host.

Mail Priority

This register defines the priority level of the email. It can be configured to Low, Normal, or High priority.

Event Priority

This numeric bounded register allows you to set the event priority of an email error, from 0 (lowest priority) to 255 (highest priority).

Notification Wait Period

This register defines the amount of time in seconds that the module waits before sending the email. This allows Cancel input logic to be implemented and/or aggregation/summary email information to be gathered and sent over this period of time.

XML Override File

This register holds the optional full path to the XML filename containing override elements for the setup registers in this module. If an element is contained in the file, it overrides what has been specified in the associated setup register. Only the setup registers you want to override need to have XML attributes in the file. This allows for easier maintenance of email distribution lists, for example, when they are used across multiple modules.

NOTE: It is strongly recommended that you use %VIPDIR% as a shortcut to the Virtual Processor configuration directory. For example, %VIPDIR%\ExampleEmail.xml. Using %VIPDIR% ensures that the configuration is kept together for system backups.

Output registers

Notification Wait Time Left

This register is a diagnostic indication of the time left in the Notification Wait Period (if programmed).

Success

This register indicates that the SMTP Server Host returned a result indicating that the email was sent successfully.

Fail

This register indicates that the SMTP Server Host returned a result indicating that the email was not sent after the specified number of retries.

Event

Any events produced by the Email module are recorded in the Event register.

Possible events and their associated priority numbers are shown in the following table.

Event priority group	Priority	Description
Setup Change	10	Input links, setup registers or labels have changed.
Email Results	25 (default)	Email sent successfully. Could not send email. Email send canceled.