How Email Engine works
This topic presents a sample scenario that demonstrates how Email Engine interacts with the AR System and your mail server. The following figure presents a sample environment for an Email Engine implementation, including the flow of activity.
How Email Engine interacts with the AR System server
In the XYZ Company, Shelly needs a list of the latest issues stored in the Help Desk Incident form. She wants the results of this query to be returned in an easy-to-read email. Shelly also wants to make sure that her coworkers are copied with the results of this query. The steps to achieve this are as follows:
- The local administrator installs Email Engine, configuring Incoming and Outgoing mailboxes to work with the company mail server.
After Email Engine is started, it contacts the AR System server. It then reads all the entries in the AR System Email Mailbox Configuration form and creates Incoming and Outgoing mailboxes based on that information. - After the administrator notifies the user base that Email Engine is running, Shelly composes an email instructing the Email Engine to perform a query of the HD Incident form. She uses specifically formatted instructions to be read and understood by the Email Engine. She sends this message to an email account on the company mail server that Email Engine polls for incoming.
After waiting for a prescribed polling period, Email Engine logs in to the company mail server by using the email account information gathered during step 1. Because the mailbox information tells the Email Engine that this email account is to be treated as an Incoming Mailbox, the Email Engine reads the most recent emails from this account, by using one of several email protocols (POP3, IMAP4, MBOX, MAPI, or EWS), including the email that Shelly sent.
If you want to use the MAPI protocol, you should use Exchange Server 2013 or earlier. However, if you want to use the EWS protocol, you should use Exchange Server 2016 or later.
- Email Engine interprets the instructions and translates them into API calls to the AR System server, attempting to fulfill her query request.
- The AR System server responds to Email Engine API calls with the appropriate query information for the HD Incident form.
- Email Engine uses the formatting instructions in the Outgoing Mailbox to construct an email message to the company mail server. Email Engine then transmits the message with instructions to send the message to Shelly and her coworkers by using the outgoing email protocol (SMTP, MAPI, or EWS).
- Shelly and her coworkers log in to the mail server, and they find the email constructed by the Email Engine, which contains a neatly formatted list of the most recent requests.
This example illustrates the relationship between the Email Engine and other systems in a simplified environment. Your environment might differ from the one presented here. For example, the Email Engine might reside on the same system as the AR System server. Alternatively, you might configure the Incoming Mailbox and Outgoing Mailbox to use the same email account on your mail server.
Multiple mail server support
You can configure multiple mail servers for an Email Engine installation. For each configured mail server, you can specify a failover mail server. If the mail server being used stops working, the Email Engine switches to the available failover mail server and continues processing mails. The following figure depicts this functionality.
Multiple mail servers configured for failover
In the illustration, M1 is specified as the primary mail server, and M2 and M3 are specified as failover servers. If the Email Engine detects that M1 is not working, it checks whether M2 is available, and if so, it switches to M2.
The Email Engine then tries to connect to M1, and if that is not yet working, it connects to M2. Then, if the Email Engine detects that M2 is not working, it checks for the availability of M1. If M1 is still not working, it looks for the failover server for M2, which is M3. If M3 is available, it switches to M3 and continues processing messages as described in the preceding note.
If none of the configured mail servers is working, the Email Engine produces an error and stops processing.
When switching from a server being currently used to its failover server, an entry is added to the stderr.log (Windows) or emaild.sh_log (UNIX) file. However, when switching back from the failover server to the primary server, no change is made to stderr.log or emaild.sh_log.
The multiple mail server support is currently available for the SMTP protocol only.
Improving the appearance of email
The following figure illustrates how the Email Engine can assign HTML templates to outgoing email to improve its appearance.
Templates dynamically assigned through workflow
Administrators can create attractive HTML pages to use as header, footer, result, and content templates. They might work with a graphic artist to create interesting bitmaps. They can also design a data-driven workflow that dynamically assigns the correct templates based on the ticket's impact. The templates might be designed so that users can quickly tell whether a ticket's impact is urgent, high, medium, or low.
The following steps illustrate the scenario:
- Shelly is visiting an important client in Chicago. She needs information from the corporate website within the hour to close an important deal, but the web server is down and her web client keeps returning error messages. She composes an email with status marked Urgent and sends it to the Incoming mailbox.
- The Email Engine receives the email from the mail server. It parses the instructions in her email, and makes the appropriate API calls to the AR System server.
- The server executes a filter that triggers a Notify action. Under normal circumstances, email notifications are formatted with a standard HTML header and result template. But if a submission is marked Urgent, the filter workflow creates an email notification with the Urgent header template.
- The Email Engine constructs the message according to formatting instructions contained in the Outgoing Mailbox it is using. This message consists of the field values from the HD Incident form (submitter, short description, status, assignee, and so on) along with the header and reply templates that are stored by the AR System server in the AR System Email Templates form. The Email Engine then transmits the message to the mail server with instructions to send the message to Francie Frontline, the first-line Customer Support engineer.
- Francie Frontline logs in to the mail server to see if she has new mail. She sees the Urgent email constructed by the Email Engine. She clicks the URL in her email, and the ticket opens in her browser. Because the email is marked Urgent, its importance jumps to the top of her To Do list. She troubleshoots and quickly resolves the problem. When Francie marks the ticket as Fixed, the server fires a filter Notify action. Shelly then receives an email notification from the system that her web access problems have been solved. She can now access the information she needs to close her sale.
For more information, see Using-templates-with-outgoing-email.