Tridium - Installation and Configuration of E-mail Service

Installation and Configuration of E-mail Servic


This article describes how to install and configure the EmailService emailService.png in EC-NetAX. Email service is required whenever you specify an "EmailRecipient" in your station or application. For example, you can route both alarms and reports via email using the EmailRecipient, as shown below.

Note
The EmailRecipient component for alarms is located in the email palette and is different from the EmailRecipient that is used for reports (located in the ReportService palette). These two components are different. It is important to use the appropriate EmailRecipient component, as indicated in the illustration, below.

Important information when setting up an account:

-          Enable Debug in the Properties Sheet (TRUE) in the outgoing and incoming e-mail so that you can see errors.
-          Even if you are only sending Outgoing e-mail you MUST setup an Incoming E-mail account as well.
-          In the Command Prompt enter “ping smtp.mysite.com” this way we know that we are hitting the server or not.
-          The Host must create a FULL account for you, if not then in some cases e-mails may not pass their firewall.

Alarm EmailRecipient and Report EmailRecipient require a configured Email Service
emailRecipReportAlarm.png

Related Articles

Installing and Configuring Email Accounts

The following sections describe how to install and setup outgoing and incoming email accounts under the email service in NiagaraAX:

Install and Enable Email Service

Note
If you already have EmailService installed, you do not need to perform this procedure. Refer to Configure_Email_Service

To install the email service in NiagaraAX, do the following:

1. From the Workbench toolbar, select Palette from the Palette menu. The Palette Side Bar opens.

Use the Palette menu from the WorkbenchAX toolbar menu.
PaletteToolbarMenu.png

2. On the Palette Side Bar Toolbar, click the Open icon. The Open Palette dialog box appears.

3. Browse to the email module, select it, and click the OK button. The email palette appears in the palette side bar pane.

4. Drag and drop the EmailService component onto the Services node.

Drag EmailService to the Services Node.
SelectModuleEmailService.png

5. In the EmailService property sheet view, set the Enabled property to true and click the Save button at the bottom of the view. EmailService is enabled and the Status property should display {ok}.

Install and Configure OutgoingAccount

1. From the email palette, drag and drop the OutgoingAccount component outgoingAcct.png onto the EmailService component in the nav tree. The EmailService and OutgoingAccount appear in the nav tree, as shown below.

EmailService with OutgoingAccount in the nav tree
emailOutAcctAdd.png

2. In the nav tree, right-click on the OutgoingAccount component and select Property Sheet, from the popup menu. The property sheet view displays.

3. In the OutgoingAccount property sheet view, configure the properties as described below:

Hostname
This is the name of the mail server. For example mail.acme.com could be a Hostname.
Port
This is the port number associated with the email account. Typically email outgoing account port numbers are port "25", however, if you leave the setting at its default value of "-1" the OutgoingAccount will search for and use a valid port.
Account
This is the name of the distinct account that is authorized for access to the "Hostname" mail server. For example, if you are using an email account named "controls@acme.com" on the host described above, the account name is simply "controls". The Hostname in this case could be "mail.acme.com".
Password
This is the login credential for the Account specified in the previous field. Increasing the pollrate value increases the time between polls. During the time between polls, emails may be queued (up to the max queue size) until the next poll time. At the next poll time all queued emails are sent.
Pollrate
This field allows you to specify how often the account executes a send action.
Enabled
This field allows you to activate or deactivate the account by choosing true or false, respectively.
Status
This is a read-only display of the condition of service. The status displays {ok} if the account is polling successfully. Other indications include:
    • {down} which means that the polling is unsuccessful, perhaps because of an incorrect Hostname, Password, or Account name.
    • {disabled} because the Enable property is set to false
Last Poll Success, Last Poll Failure
These two properties display the time (in hours and minutes) of the last polling success and failure.
Last Poll Failure Cause
This display-only field provides an error message to indicate a reason for polling failure.
Debug
This Boolean property turns Debug mode on true or off, as desired. When Debug is turned on, you can see detailed debug information in a station's standard output view (WorkbenchAX Platform > Application Director view) when the Station tries to send or receive email. This can be used to troubleshoot the accounts and faults.
Use Ssl
The Ssl (Secure Socket Layer) option is available on the OutgoingAccount starting in NiagaraAX-3.5. The option list allows you to disable Ssl (false) or enable it (true). Enable Ssl for communication with a host email server that requires it.
Transport
This field allows you to select from available options for email communication. The default setting and most common is SMTP.
Connection Timeout
This configurable field setting controls how long the station waits for a response from the mail server before generating an exception and setting the fault cause. It waits for the next scheduled poll and attempts to contact the mail server again at that frequency.
Use Authentication
This property allows you to specify that login credentials are required for sending any email. Sometimes authentication is not required for emails routed to recipients in the same domain. Setting this property to true makes the login credentials mandatory for any email.
Reply To
This field specifies the contents of the "From:" field in the email that is sent.
Persistent, Persistent Directory
Setting the Persistent property to true saves each queued email as an xml file in the designated persistence directory. Once the emails are actually sent, the xml files are deleted from the directory. The purpose of this is to keep a copy of the emails in the queue which would be lost if the station was stopped prior to the emails being sent. When the station restarts, emails are loaded from the "Persistent Directory" back to the queue.
Email Queue Tracking Properties
"Queue" is where emails reside while they are waiting to be sent. Assuming that the Account Status is "ok", typically, the length of time that an email is in the queue depends on the "Pollrate" setting. The following properties relate to the queue and mail management properties
Allow Disabled Queuing
This property (when set to true) allows emails to reside in the queue even when the Enabled status is set to false.
Queue Size
This property refers to how many emails are currently in the queue (waiting to be sent). You can clear the queue at any time by right-clicking on the appropriate outgoing account property outgoingAcct.png and selecting Actions > Clear Queue from the popup menu.
Max Queue Size
This property allows you to specify how many emails are allowed to occupy the queue.
Number Sent
This property displays the number of emails that have been sent. You can reset this number to zero at any time by right-clicking on the appropriate outgoing account property outgoingAcct.png and selecting Actions > Reset Number Sent from the popup menu.
Max Sendable Per Day
This property allows you to specify how many emails may be sent in one day.
Number Discarded
This read-only property (NiagaraAX-3.5 and later) displays a value to indicate how many emails did not successfully send.
Last Discard
This read-only property (NiagaraAX-3.5 and later) displays a date and time value to indicate when the last email did failed to send.
Last Discard Cause
This read-only property (NiagaraAX-3.5 and later) displays an error message that indicates the cause of the last email send failure.

4. Click the OK button to save all settings. Configuration of the OutgoingAccount is complete.

5. Test the OutgoingAccount as follows:

  • Right-click on the OutgoingAccount property outgoingAcct.png and select Actions > Send from the popup menu. An email form appears as the Send dialog box, as shown below.

Testing EmailService configuration by sending a "test" email
sendDiaglog.png

  • Fill out the email form using valid account names and click the OK button to send an email. An email should be sent within the time specified by the Pollrate property.
  • Check the following properties:
    • Status: should be {ok}
    • Last Poll Success: should indicate a recent time
    • Last Poll Failure: should be "null" or an earlier time than "Last Poll Success"
    • Queue Size: should be 0 (unless another email has just queued up).
    • Number Sent: should increment by one with your test email.
  • Finally, check that the email is received by the target recipient.

Install and Configure IncomingAccount

1. From the email palette, drag and drop the IncomingAccount component incomingacct.png onto the EmailService component in the nav tree. The EmailService and IncomingAccount appear in the nav tree, as shown below.

EmailService with IncomingAccount in the nav tree
emailInAcctAdd.png

2. In the nav tree, right-click on the IncomingAccount component and select Property Sheet, from the popup menu. The property sheet view displays.

3. In the IncomingAccount property sheet view, configure the properties as described below:

Hostname
This is the name of the mail server. For example mail.acme.com could be a Hostname.
Port
This is the port number associated with the email account. Typically email incoming account port numbers are port "110", however, if you leave the setting at its default value of "-1" the IncomingAccount will search for and use a valid port.

Caution
With the default configuration (see Delivery Policy property, below) the incoming email account deletes all emails from the mail server when it checks the account to retrieve new email, even if the emails are already marked as read by another email client. If permanent retention of the emails is required then do one of the following:
  • change the Delivery Policy setting from Delete
  • configure a second service account which the mail server forwards emails to and configure the station's incoming account to check the second service account.

Account
This is the name of the distinct account that is authorized for access to the "Hostname" mail server. For example, if you are using an email account named "controls@acme.com" on the host described above, the account name is simply "controls". The Hostname in this case could be "mail.acme.com".
Password
This is the login credential for the Account specified in the previous field.
Pollrate
This field allows you to specify how often the account connects to the mail server and checks for unread mail messages. Increasing the pollrate value increases the time between polls.
Enabled
This field allows you to activate or deactivate the account by choosing true or false, respectively.
Status
This is a read-only display of the condition of service. The status displays {ok} if the account is polling successfully. Other indications include:
    • {down} which means that the polling is unsuccessful, perhaps because of an incorrect Hostname, Password, or Account name.
    • {disabled} because the Enable property is set to false
Last Poll Success, Last Poll Failure
These two properties display the time (in hours and minutes) of the last polling success and failure.
Last Poll Failure Cause
This display-only field provides an error message to indicate a reason for polling failure.
Debug
This Boolean property turns Debug mode on true or off, as desired. When Debug is turned on, you can see detailed debug information in a station's standard output view (WorkbenchAX Platform > Application Director view) when the Station tries to send or receive email. This can be used to troubleshoot the accounts and faults.
Use Ssl
The Ssl (Secure Socket Layer) option is available starting in NiagaraAX-3.5. The option list allows you to disable Ssl (false) or enable it (true). Enable Ssl for communication with a host email server that requires it.
Store
This property allows you to choose between two standards of mail retrieval. You need to choose the option that is in use by your host mail server:
    • Imap
    • Pop3
Delivery Policy
This property (available starting in NiagaraAX-3.5) provides an option list that allows you to select how the incoming email account handles incoming emails at the mail server.

The following options are available:

Delete
With this configuration the incoming email account deletes all emails from the mail server when it checks the account to retrieve new email, even if the emails are already marked as read by another email client.
Mark As Read
This option marks all emails as read on the mail server when it checks the account to retrieve new email.
Mark As Unread
This option marks all emails as unread on the mail server when it checks the account to retrieve new email.

4. Click the OK button to save all settings. Configuration of the IncomingAccount is complete.

Add Feedback