Configure the email settings for an Alarm worksheet

Your project can automatically send emails to specified addresses when alarm events occur. Configure the email settings for an Alarm worksheet in order to customize the format and frequency of those emails.

Before you begin this task, make sure you have configured an outgoing email server and account for your project. There are two ways to do this:

• Configure the default email settings for your project; or

• Configure a script that calls the CnfEmail function at least once. This is typically done in the VBScript Startup Script, so that the email settings are configured before anything in the project tries to send email, but it can be done again in other scripts in order to change the settings during project run time.

You do not need to have an email client application (such as Microsoft Outlook) installed on the computer or device that hosts the project runtime, because the project runtime can connect directly to the email server. In other words, the project runtime itself acts as an email client.

Note: Keep in mind that the email settings for your project, as described above, are separate from the email settings for an Alarm worksheet, as described below.

This task assumes you have created an Alarm worksheet and that worksheet is open in the Screen/Worksheet Editor. The procedure below begins at that point.

To configure the email settings for an Alarm worksheet:

1. In the header of the Alarm worksheet, click Email Settings.

   The Email Settings dialog box is displayed. Email is disabled by default for each Alarm worksheet, so most of the settings in this dialog box are not available until email is enabled.

2. Select the Enable send automatic email option.

   All of the settings in the dialog box become available.

   

3. In the To box, type the primary email address to which you want send alarm messages. If you want to send to more than one address, insert semicolons (;) to separate the addresses.

   You can also send "carbon copies" and "blind carbon copies" to other email addresses. Type those addresses in the Cc and Bcc boxes, respectively. The same email is sent to all of the addresses at the same time.

   The To, Cc, and Bcc settings each have a limit of 1024 characters. These fields accept String expressions. However, when the string expression is evaluated, the resulting value is subject to the same character limit.

4. In the Subject area, in the Custom box, type the text that you want to use as the subject of each email. This field accepts String expressions.

   Alternatively, you can select Use alarm message in order to use the actual alarm message as the subject of the email, but this is not recommended because the alarm message is included in the body of the email.

The procedure above describes the minimum that you need to do in order to send email for the Alarm worksheet. When the alarms events that are configured in the worksheet occur during project run time, corresponding alarm messages are added to an internal memory buffer, and then those messages are periodically sent as email until the buffer is empty.

If you want to customize the format and frequency of those emails, review the additional settings described below:

Send 1 message per email

Select this option in order to send one alarm message (event) per email, each time sending is triggered (see Send Trigger below). Otherwise, all of the messages currently stored in the buffer are sent as a batch in a single email.

This option is automatically selected and cannot be cleared when the Use alarm message option is selected for the subject of the email.

Remove failed messages from the buffer

Select this option in order to remove alarm messages (events) from the buffer after the project runtime tries to send them, even if there is an error (failure) and the email is not sent successfully. Otherwise, the messages are kept in the buffer until the email is sent successfully, or until the buffer is full (see Max buffer size below).

Send email when alarm is

Select which alarm events should generate messages:

Each type of event can be selected individually, but that selection applies to all alarms configured in the same worksheet. If you want to generate messages when some alarms but not others become active, separate those alarms into different worksheets.

Current Status

You can type the name of a project tag in this box. During project run time, this tag is updated with a numeric value that indicates the status of the latest email:

Current Error

You can type the name of a project tag (String type) in this box. During project run time, this tag is updated with the error message describing the result of the last email that the project tried to send. The error message is a string, so the project tag must be String type in order to hold the message.

Message Format

This interface allows you to customize the format of the alarm messages that are included in the body of the email:

• Day, Month, Year, Hour, Minute, Second, MS: The options checked will compose the timestamp for each alarm message. MS stands for milliseconds.

• Items: The options checked will compose the actual message for each alarm. Use the Move Up and Move Down buttons to change the order of the items.

• Separator: The separator that is inserted between items in the alarm message. This is important if you have set up another program to receive the emails and then automatically parse the messages.

  The Sample box displays an example of the message format as you customize it.

  Send Trigger

  When the value of this tag/expression changes, the alarm messages (events) currently stored in the buffer are sent according to these email settings. The default trigger is the Minute tag, which is a system tag that updates each minute of the clock on the computer or device that hosts the project runtime, and it prevents the messages from overloading the email server or "spamming" the email recipients. The default trigger might not be frequent enough to keep up with alarms as they occur, however, especially if you have selected the Send 1 message per email option; if there are 10 messages stored in the buffer and only one message is sent per minute, then it will take 10 minutes to send all of the messages. Therefore, you may configure a different tag/expression that can accommodate the actual behavior of your project.

  Max buffer size

  This is the maximum number of alarm messages (events) that can be stored in the buffer. The buffer stores messages on a "First In, First Out" (FIFO) basis, so if new messages are added after the maximum has been reached, then the older messages are removed without being sent. The default maximum is 1000 messages, but you can increase it if the computer or device that hosts the project runtime has sufficient memory.

  Buffer size

  You can type the name of a project tag in this box. During project run time, this tag is updated with the number of alarm messages (events) currently stored in the buffer.

  Clear Buffer

  You can type a tag/expression in this box. When its value changes during project run time, all alarm messages (events) currently stored in the buffer are removed and will never be sent.

  Disable send

  You can type a tag/expression in this box. While its value is TRUE (that is, not 0) during project run time, the sending of email is disabled for this Alarm worksheet. Alarm messages (events) currently stored in the buffer are not sent, regardless of Send Trigger, and new messages are not added to the buffer.

When you are done, click OK to save the settings and close the dialog box.