Configuring EVMail

EVMail is configured as a task. If you are setting up EVMail for the first time, you will need to create the task. Use the button labeled Add to add the task from the Task Manager screen, or use the Edit button to modify the attributes that control the EVMail task. Select the EVMail Task task name and observe a screen similar to:

EVMail configuration screen

Basic Configuration

To configure EVMail, you will need a properly configured POP3 mailbox and you will need its username and password. You will also need to know the port to use for communication with the mailbox.

Next, you will need to identify an ExtraView user account, and a user role that EVMail will utilize. These, along with a nominated Business Area and Project, determine the add and edit screen layouts that will be used by EVMail to create new issues and to update existing issues. When selecting these values, take into account the standard licensing condition of ExtraView, i.e. non-licensed guest role users cannot update issues. Therefore, if you select a guest user for the runtime account, only new tickets will be created and you will not be able to update issues.

Note: The MAILBOX_USER value should never be the email address of a user within the ExtraView system. If you do this, there is a chance for an infinite loop to be set up where incoming emails generate notification to this user which then reply to the same address, thereby generating a new event which repeats itself.

Note: The MAILBOX_USER value should always be set to the same value as the behavior setting named EMAIL_FROM_ADDRESS. This ensures that updates to issues made by users and resubmitted are sent back to the same email address that ExtraView monitors.

You will then need to set up the fields that the EVMail task will populate - there are some field options that map to portions of the incoming email message according to whether you are inserting a new issue or updating an existing issue.

EVMAIL_BODY_UDF and/or
EVMAIL_BODY_HTML_UDF		 For a new issue being created, use either or both of these fields to store the body of the email message. This allows you to store the body as text, HTML or both.  Typically this will be mapped to the DESCRIPTION field or an HTML AREA field
EVMAIL_BODY_UPDATE_UDF and/or EVMAIL_BODY_HTML_UPDATE_UDF For issue updates, use either or both of these fields to store the body of the email message. This allows you to store the body as text, HTML or both.  Typically this will be mapped to the COMMENTS field or an HTML AREA field, so that successive updates will create a new entry in this log area field.  Note that the COMMENTS field may use an option in the data dictionary to use it directly with HTML.
EVMAIL_SUBJECT This ExtraView field will be where the subject of the email message is placed. Typically this will be the SHORT_DESCR field

You can select other fields and set values, allowing you to set list values and user fields when creating new issues. The syntax for these fields is EVMAIL_FIELDNAME, where FIELDNAME is the field name of the field being mapped. For example, these are valid expressions:

EVMAIL_AREA = 10 You must use the AREA_ID for the AREA field
EVMAIL_PROJECT = 19 You must use the PROJECT_ID for the PROJECT field
EVMAIL_STATUS = NEW You must use the name for inbuilt fields
EVMAIL_ORIGINATOR = BSMITH You must use the User ID for user fields
EVMAIL_COMPONENT = 12435 You must use the UDF_LIST_ID for user defined list fields
EVMAIL_INSTRUCTIONS = Here are instructions You can popuplate text, text area and log area fields with text

Note: Updating existing issues will only result in the update of the EVMAIL_BODY_UPDATE_UDF field.

The values for these fields are database values or the internal ID value of the field (i.e. the UDF_LIST_ID value), not the title of the field. You can find the internal ID value by placing your mouse cursor over the list value in its maintenance screen, and looking at the status bar of your browser.

Finding the UDF_LIST_ID internal ID value

You can use a similar technique to find the AREA_ID for the AREA field and the PROJECT_ID for the PROJECT field. Look for the p_aid parameter for the AREA and the p_pid parameter for the PROJECT field.

All fields mapped in the Configure EVMail screen must be on the add layout, for the ExtraView user ID, their role, their default Business Area and their Project.

The default behavior of the EVMail task is to take the email address in the From: section of the email message, and to search for a matching user in ExtraView who has that same email address in either their primary or secondary email address field in their account. If a user is found, their User ID is used to populate the ORIGINATOR field. If no user is found, the user specified by EVMAIL_ORIGINATOR will be set into the ORIGINATOR field.

Full List of EVMail Settings

EVMAIL_FIELDNAME See the description above on how to map different fields from EVMail to ExtraView
EVMAIL_ALLOW_HTML_MSG Valid values are YES, NO and PARSE. If this is not specified, the default value is PARSE
EVMAIL_ALLOW_HTML_MSG_FAIL_TEMPLATE This is used only if the EVMAIL_ALLOW_HTML_MSG parameter is set to is NO. If it does not exist, then SMTP_MSG_FAIL_TEMPLATE is used, if it exists
EVMAIL_ATTACH_EML This parameter allows you to attach a copy of the received email in EML format to the created or edited issue when it is set to YES. A setting of NO or the absence of this entry means the attachment will not sent with the mail
EVMAIL_BODY_UDF For a new issue being created, use this field to store the body of the email message as text.  Typically this will be mapped to the DESCRIPTION field
EVMAIL_BODY_HTML_UDF When you want to retain the HTML within the body of an incoming email, use this in place of, or as a complement to EVMAIL_BODY_UDF.  This field should be an HTML AREA field
EVMAIL_BODY_UPDATE_UDF For issue updates, use this field to store the body of the email message. This allows you to store the body as text.  Typically this will be mapped to the COMMENTS field, so that successive updates will create a new entry in this log area field.
EVMAIL_BODY_HTML_UPDATE_UDF When you want to retain the HTML within the body of an incoming email that is updating existing issues, use this in place of, or as a complement to EVMAIL_BODY_UDF.  This field should be an HTML AREA field or a LOG AREA field configured to use HTML
EVMAIL_CC_UDF This parameter takes the entries in the CC field of an incoming email being processed by EVMail. You may set the value of this parameter to a field with a display type of text or text area.

The contents of the EVMAIL_CC_UDF field are not cumulative, but the issue history will show the successive values from each issue update. The value stored in the field will simply be the CC addresses of the current incoming email message.

This setting only works with ExtraView Enterprise versions.
EVMAIL_FROM_UDF You may set the value of this parameter to a field with a display type of text or text area.

If an incoming email is processed by EVMail and ExtraView fails to find a valid user who has an email address or alternate email address that matches the incoming message FROM address, Extraview will place the incoming FROM email address in the EVMAIL_FROM_UDF parameter. If ExtraView finds a matching user, it will not populate the new field, and will simply set the Originator field to the identified user account.

This action works only when creating new issues - the EVMAIL_FROM_UDF field is not modified when an existing issue is being updated. This setting only works with ExtraView Enterprise versions.

This setting only works with ExtraView Enterprise versions.
EVMAIL_ID_REGEX This is a regular expression used to parse the subject line and search for an ExtraView ID value. If an ID is found, EVMail attempts to update a matching issue ID in ExtraView. If no matching ID is found, a new issue is created. If you enter an invalid regular expression, ExtraView will report this information to the application server log.
EVMAIL_SUBJECT This ExtraView field will be where the subject of the email message is placed. Typically this will be the SHORT_DESCR field
EVMAIL_SUBJECT_LOOKUP The EVMAIL_SUBJECT_LOOKUP setting works in addition to the EVMAIL_ID_REGEX setting by searching existing records for matching subject line. When no ExtraView ID is detected in the subject line and EVMAIL_SUBJECT_LOOKUP is set to YES, then existing records are searched by the field specified in the EVMAIL_SUBJECT setting and matched against the incoming email subject line.

If a record matches, then that record is updated. Otherwise, when no match is found, then a new record is inserted. Note that subject line prefixes such as Re: and Fwd: are removed from the incoming email subject line for the purposes of performing the search and match. Also, the field specified in the EVMAIL_SUBJECT setting must be configured in Data Dictionary to have their Filter Criteria attribute set to Yes, so that a query can be executed with that field as a filter.

If multiple records match the subject line, then a new record is inserted as opposed to updating multiple existing records.
EVMAIL_TO_UDF You may set the value of this parameter to a field with a display type of text or text area.

EVMail parses the TO header within the incoming email and extracts the email address(es) in this list. If the EVMail address is in the list, it is removed. This may result in an empty list. If the list is not empty, EVMail creates a semi-colon separated list of email address and uses this as the value within the EVMAIL_TO_UDF field. This processing happens for both emails that create new issues within ExtraView as well as for emails that update issues within ExtraView.

The contents of the EVMAIL_TO_UDF field are not cumulative, but the issue history will show the successive values from each issue update. The value stored in the field will simply be the TO addresses of the current incoming email message.

This setting only works with ExtraView Enterprise versions. Great care should be taken in the use of this parameter, as it is possible to generate an endless loop whereby an email generates an email that is processed by EVMail, generating an email notification that is again seen by EVMail and updates the same issue, ad infinitum.
PARSE_EMAIL
PARSE_FIELD.STATUS PARSE_FIELD.COMMENTS
PARSE_FIELD.DUE_DATE		 This collection of properties allow parsing of incoming mails to ExtraView.

You may configure the parsing of the incoming email message subject line and the body looking for specific tags to specify the field and value to assign to the ExtraView record being created or updated.

The PARSE_EMAIL setting must be configured to one of three values:

  • INSERT enables the feature for new records only
  • UPDATE enables the feature for updates to existing record
  • BOTH enables both inserts and updates

If the setting is commented out or set to any other value, then the feature is not configured correctly and is not used.

The PARSE_FIELD setting specifies the field name to map to the tag expected in the incoming email message, as follows:

PARSE_FIELD.<ddname> = <tag>

where <ddname> is the field name in Data Dictionary and <tag> is any text pattern that appears in the subject or body of the incoming email.

Note: Do not use the equals character within <tag>.

The value to set the field to must follow the tag in the email message, and must be on the same line as the tag in the email body. For example, to specify value of John Doe for the [Reporter] tag:

[Reporter] John Doe

In the subject line, the value must be enclosed in double-quotes, separate from the rest of the subject line text. For example, to specify value of High for the [Severity] tag:

Subject: [Severity] "High" - The roof is leaking

Multi-line text or multi-list values must be ended with the same tag name within the email body.

For example, to specify multi-line text for the [Comment] tag (i.e. a log area display type field):

[Comment] This is a multi-line
comment that spans
three lines
[Comment]

When this setting is used, but the field configured with PARSE_FIELD does not exist on the Add or Edit screen layout, or the EVMail user does not have write access to the field, or the value specified in the email is not valid, the expected behavior for the field is to not be assigned a value by EVMail.  A warning message is written to the ExtraView application log.

If you are writing to a multi-valued list field, then values are additive, i.e. the new values are added to existing values in the list.

If you mistakenly utilize the same tag more than once within the email message, only the first occurrence is processed and the others are ignored.

Examples

PARSE_FIELD.TEST_CURRENCY = $$Currency Test$$
PARSE_FIELD.DUE_DATE = [Due by]
PARSE_FIELD.TEST_DATE2 = [Date test]
PARSE_FIELD.CUST_RMA_NUM = "number test"
PARSE_FIELD.TEST_DECIMAL = (Decimal Test)
PARSE_FIELD.CUST_LIST = /Customer Name/
PARSE_FIELD.CUST_LIST_MULTI = #Multi-Customers#
PARSE_FIELD.TEST_POPUP_SINGLE = 'popup'
PARSE_FIELD.TEST_POPUP_MULTI = __multi-popup__
PARSE_FIELD.TEST_HTML_AREA = <HTML>
PARSE_FIELD.TEST_PRINT_TEXT = --PRINT--
PARSE_FIELD.TEST_RADIO_H = hRadio
PARSE_FIELD.TEST_RADIO_V = vRadio
PARSE_FIELD.CUST_SELECT_TABS = {tabs}
PARSE_FIELD.CUST_ADDRESS = |Address|
PARSE_FIELD.CUST_EMAIL = @EMAIL@
PARSE_FIELD.IT_REQUESTOR = *User*
PARSE_FIELD.TEST_USER_MULTI = ++USERS++
SMTP_CC Other email addresses to copy when sending auto-reply or failure messages back to the sender of the email
SMTP_FAIL_MSG_TEMPLATE The database name of an Ad Hoc email template to use when sending out failure messages. The template supports the use of the special variable, $$BODY$$.  If you include $$BODY$$ in the template, the body of the original incoming email will be included.
SMTP_FROM The email address used when sending auto-reply or failure messages back to the sender of the email
SMTP_NAME The friendly name used when sending auto-reply or failure messages back to the sender of the email
SMTP_REPLY_TEMPLATE The database name of an Ad Hoc email template to use when sending out auto-reply messages. The template supports the use of two special variables, $$ID$$ and $$BODY$$. If you include $$ID$$ in the template, then the ID of the newly created issue is retrieved and included in the template email. If you include $$BODY$$ in the template, the body of the original incoming email will be included.

The behavior of the last two parameters controls how HTML-based incoming emails are handled.

  1. Accept HTML mail as is, and place it into an HTML area field, trying to preserve the formatting - the assumption is that you are mainly receiving short emails, and you want to attempt to preserve HTML constructions such as tables and links
  2. Strip the incoming HTML-formatted mail of HTML tags, and place the contents into a text area or comments field. ExtraView will parse the text, removing as much HTML as possible. This is not a perfect solution, as some tags may not be recognized and any poor HTML may not be rejected.
  3. Reject the incoming HTML-only mail and send back to the submitter a rejection notice.

Configuring RUNTIME_ Parameters

  • For updates to occur, choose a RUNTIME_USER_ID that occupies a real license as opposed to a GUEST user license. If you pick a GUEST user as the RUNTIME_USER_ID, then issues will only ever be created, never updated
  • The RUNTIME_USER_ROLE needs to be a role that has access to the fields and layouts for the Business Area and Project of issues that you want to create and/or update. Again, if you select the GUEST role, issues will only ever be created, and never updated
  • RUNTIME_AREA_NAME and RUNTIME_PROJECT_NAME - these parameters determine the Business Area and Project of issues created by EVMail.

Sample EVMail configuration

RUNTIME_USER_ID = BSMITH
RUNTIME_AREA_NAME = CUST_ISSUES
RUNTIME_PROJECT_NAME = CUST_ISSUES_DATA
RUNTIME_USER_ROLE = SUPPORT

MAILBOX_TYPE = POP3
MAILBOX_PORT = 110
MAILBOX_SECURE = NO
MAILBOX_SERVER = mail.mycompany.com
MAILBOX_USER = support
MAILBOX_PASSWORD = myPassword

SMTP_FROM = support@mycompany.com
SMTP_NAME = "The Support Team"
SMTP_CC = leeann@mycompany.com
SMTP_REPLY_TEMPLATE = SUCCESS_EMAIL

EVMAIL_ID_REGEX = [ExtraView-(d+)]
EVMAIL_BODY_UDF = DESCRIPTION
EVMAIL_BODY_UPDATE_UDF = CUST_DESC
EVMAIL_SUBJECT = SHORT_DESCR
EVMAIL_CATEGORY = EMAIL
EVMAIL_STATUS = NEW
EVMAIL_ORIGINATOR = DEV

 

Handling Issue Updates from EVMail

When a user sends an email to ExtraView, EVMail examines the incoming email to determine whether this is a reply to an existing issue which should update the existing issue, or whether to generate a new issue within ExtraView. This determination is made by parsing the subject line of the incoming email. If the EVMail utility is able to parse a valid, existing issue ID out of the subject line, then it is assumed that the mail is being used to update an issue; else it is assumed that the mail is meant to generate a new issue.

One consequence of this is that when a user replies to an email notification which was generated by ExtraView automatically, the original notification will be included in the reply, simply adding to the update with information that already exists. To eliminate this, the value within a behavior setting named EVMAIL_DELIMITER_TEXT is used. This value is embedded with invisible tags within HTML emails from ExtraView to surround the entire contents of the outgoing email. When EVMail is updating the issue it looks for the value of the behavior setting and removes all text between the tags. Thus, only the new comment made by the user is added to the issue.

When issues are updated via EVMail, the Last Change User field is set to the value of the RUNTIME_USER_ID, and not to the person who sent the email.

Note that if EVMail is running under with a user whose only has a GUEST role, updates to issues are not permitted.

EVMail and the ExtraView ALT_ID Configuration

If your ExtraView configuration is configured to use ALT_ID as the issue ID, you will have set the behavior setting named ITEM_ID_DISPLAY to a value of ALT_ID.  Once this is set, EVMail will use ALT_ID as the issue ID when matching incoming email updates.

Testing EVMail

EVMail follows all the status change rules and the ALLOW_EDIT_CLOSED behavior setting. These may be based on the user, their role, their current business area and project as configured in your installation.

If you want to bypass all of those constraints for testing purposes, and make sure that tickets are updated regardless of any rules in place, use the ADMIN user account. This account (which should not be used for ordinary purposes) bypasses all status change rules.

It is worth ensuring that your workflow does not put any issue into a status value where EVMail will not be able to update it -- you may get failures, and/or the update will be captured as a new issue within the system as opposed to an update to an existing issue.

Using a Secure Mail Server

This section is optional, and covers instructions on how to connect ExtraView to a POP3 mail server configured with SSL. If you are not using SSL with your mail server, disregard this section.

The instructions here are for a Microsoft Windows environment, but are similar for other operating systems. The basic steps to configure SSL, are to install the SSL certificate on your mail server into the Java keystore, as a trusted root certificate.

  • Use a browser to go to the web management interface for your mail server, or to some other URL provided by your email client, to access your rootca certificate
  • You should now see a dialog box warning you about the certificate. Click on the View Certificate and install the certificate. You can ignore any warning messages
  • Now that the server certificate is installed on your computer, your browser will no longer warn you when you visit the same site again. However your Java runtime JRE does not yet know about this certificate's existence until you add the certificate to its keystore. Usually you will use the Java keytool utility to manage certificates. keytool is a command-line utility with numerous arguments that allows you to create and manage keystores that house digital certificates. For the complete documentation of keytool, visit http://java.sun.com/j2se/1.3/docs/tooldocs/win32/keytool.html
  • You can list the current certificates contained within the keystore using the keytool -list command. The initial password for the cacerts keystore is changeit. For example, you may see the following in a Windows environment:
     
    C:\ExtraView\java\jre\bin>keytool -list -keystore ..libsecuritycacerts Enter default keystore password: changeit

    You will then see the something like this:

    Keystore type: jks
    Keystore provider: SUN

    Your keystore contains 11 entries:

    engweb, Wed Apr 11 16:22:49 EDT 2001, trustedCertEntry?,
    Certificate fingerprint (MD5): 8C:24:DA:52:7A:4A:16:4B:8E:FB:67:44:C9:D2:E4:16 thawtepersonalfreemailca, Fri Feb 12 15:12:16 EST 1999, trustedCertEntry?,
    Certificate fingerprint (MD5): 1E:74:C3:86:3C:0C:35:C5:3E:C2:7F:EF:3C:AA:3C:D9 thawtepersonalbasicca, Fri Feb 12 15:11:01 EST 1999, trustedCertEntry?,
    Certificate fingerprint (MD5): E6:0B:D2:C9:CA:2D:88:DB:1A:71:0E:4B:78:EB:02:41 verisignclass3ca, Mon Jun 29 13:05:51 EDT 1998, trustedCertEntry?,
    Certificate fingerprint (MD5): 78:2A:02:DF:DB:2E:14:D5:A7:5F:0A:DF:B6:8E:9C:5D thawteserverca, Fri Feb 12 15:14:33 EST 1999, trustedCertEntry?,
    Certificate fingerprint (MD5): C5:70:C4:A2:ED:53:78:0C:C8:10:53:81:64:CB:D0:1D thawtepersonalpremiumca, Fri Feb 12 15:13:21 EST 1999, trustedCertEntry?,
    Certificate fingerprint (MD5): 3A:B2:DE:22:9A:20:93:49:F9:ED:C8:D2:8A:E7:68:0D verisignclass4ca, Mon Jun 29 13:06:57 EDT 1998, trustedCertEntry?,
    Certificate fingerprint (MD5): 1B:D1:AD:17:8B:7F:22:13:24:F5:26:E2:5D:4E:B9:10 verisignclass1ca, Mon Jun 29 13:06:17 EDT 1998, trustedCertEntry?,
    Certificate fingerprint (MD5): 51:86:E8:1F:BC:B1:C3:71:B5:18:10:DB:5F:DC:F6:20 verisignserverca, Mon Jun 29 13:07:34 EDT 1998, trustedCertEntry?,
    Certificate fingerprint (MD5): 74:7B:82:03:43:F0:00:9E:6B:B3:EC:47:BF:85:A5:93 thawtepremiumserverca, Fri Feb 12 15:15:26 EST 1999, trustedCertEntry?,
    Certificate fingerprint (MD5): 06:9F:69:79:16:66:90:02:1B:8C:8C:A2:C3:07:6F:3A verisignclass2ca, Mon Jun 29 13:06:39 EDT 1998, trustedCertEntry?,
    Certificate fingerprint (MD5): EC:40:7D:2B:76:52:67:05:2C:EA:F2:3A:4F:65:F0:D8
     

  • Now you have to add the certificate you previously installed to this keystore. Begin by exporting your CA Root certificate from your browser as a DER-encoded binary file and save it as C:root.cer. Within Internet Explorer, you can view the installed certificates under Tools --> Internet Options --> Content --> Certificates. Once you open the certificates, locate the one you just installed under Trusted Root Certification Authorities. Select and click on Export. You can now save it as a DER encoded binary under your C: drive
  • Use the keytool -import command to import this file into your cacerts keystore. For example:
     
    C:\ExtraView\java\bin\keytool -alias myprivateroot -keystore ..libsecuritycacerts -file c:root.cer

    Enter default keystore password: changeit

    Owner: CN=Division name, OU=Department, O=Your Company, L=Anytown,

    ST=NC, C=US, EmailAddress?=you@company.com
    Issuer: CN=Division name, OU=Department, O=Your Company, L=Anytown,
    ST=NC, C=US, EmailAddress?=you@company.com
    Serial number: 79805d77eecfadb147e84f8cc2a22106
    Valid from: Wed Sep 19 14:15:10 EDT 2001 until: Mon Sep 19 14:23:20 EDT 2101
    Certificate fingerprints: MD5: B6:30:03:DC:6D:73:57:9B:F4:EE:13:16:C7:68:85:09
    SHA1: B5:C3:BB:CA:34:DF:54:85:2A:E9:B2:05:E0:F7:84:1E:6E:E3:E7:68
     
    Trust this certificate? [no]: yes
     
    Certificate was added to keystore
  • Run keytool -list again to verify that your private root certificate was added:
     
    C:\ExtraView\java\bin\keytool -list -keystore ..libsecuritycacerts

    You will now see a list of all the certificates including the one you just added. This confirms that your private root certificate has been added to the ExtraView Java cacerts keystore as a trusted certificate authority

  • Stop and restart your application server to pick up the new certificate.

Configuring EVMail with Microsoft Exchange as a Server

Microsoft Exchange Server 2007 and newer is recommended.  Configure these settings to achieve this connection:

MAILBOX_TYPE Set this to a value of EXCHANGE to use Microsoft Exchange Server
MAILBOX_USER Set this to the user name of the connection to Exchange
MAILBOX_PASSWORD Set this to the password of the user with which you are connecting to Exchange
EXCHANGE_URL This value should be the URL of the Exchange server

EVMail can connect to the older Microsoft Exchange 2003 Server, via OWA (Outlook Web Access). To select Exchange 2003 mailbox in EVMail use the following configuration settings.

MAILBOX_TYPE = OWA
MAILBOX_PORT = 110
MAILBOX_SECURE = YES
MAILBOX_SERVER = owa.exchange.ms
MAILBOX_USER = evmailuser
MAILBOX_PASSWORD = password
 
#These parameters are used when MAILBOX_TYPE = OWA
# for connecting to Exchange 2003 using OWA
OWA_PATH = Exchange
OWA_DESTINATION = https://owa.exchange.ms/Exchange/evmailuser@yourdomain.com
OWA_ISA = true
OWA_DOMAIN = companydomain
OWA_FBA_PATH = /exchweb/bin/auth/owaauth.dll

Notes:

  1. Do not configure these parameters for Microsoft Exchange Server if you are using a POP3 server
  2. For OWA the mailbox_port is not used, but it is a required parameter; leave its value as 110
  3. MAILBOX_SECURE - set to YES if your OWA url is https, set to NO if your OWA url is http
  4. MAILBOX_SERVER - your Exchange Server
  5. MAILBOX_USER and MAILBOX_PASSWORD - the username and password of your Exchange 2003 mailbox

Specific settings for OWA Exchange 2003 connections only - we provide sample settings to help you identify the equivalent settings in your Exchange Server.

MAILBOX_SERVER = Name of your MS Exchange Server

OWA_PATH - Exchange path for MS Exchange OutLook Web Access

The URL used to access your Outlook Web Access page is made up of the values for MAILBOX_SERVER and the OWA_PATH, e.g.

http(s)://MAILBOX_SERVER/OWA_PATH/ - should take you to your Outlook Web Access page

OWA_DOMAIN - the Exchange/Windows domain for the MAILBOX_USER account

OWA_FTA_PATH - path to Form based authentication - this can be found if you look at the HTML source of the OWA authentication/login page - search for "destination".

OWA_DESTINATION - on the OWA login page, search for the hidden field "destination" OWA_ISA - needed for use with OWA_DESTINATION

How EVMail Handles Errors

When EVMail encounters a problem, it may be either a "transient" error, i.e. one that might fix itself if the operation is tried again at a later time, or it might be a "permanent" error, i.e. one that needs a change in the EVMail configuration in order to be resolved. Examples of permanent errors include:

  1. Bad username/password for the MAIL_USER or MAIL_PASSWORD parameters
  2. Invalid values for RUNTIME_USER_ID, RUNTIME_AREA_NAME, RUNTIME_PROJECT_NAME, RUNTIME_USER_ROLE

An example of a transient errors would be the inability to connect to the mail server because of a network error. In a test situation, you can create a transient error by setting MAILBOX_PORT or MAILBOX_SERVER to an invalid value temporarily. When EVMail encounters a permanent error, it does the following:

  1. Changes the task status to ERROR
  2. Sends an email to all users in the ADMIN role indicating that EVMail is in an ERROR state Fatal Task Configuration Error
  3. Stops the task so that it no longer runs

Once the task is in an ERROR state, the following must be done to repair the error

  1. Edit the task and fix the configuration problem that caused the error, e.g. fix the MAILBOX_PORT if this is in error
  2. Change the status of the task from START_NOW to STOP_NOW
  3. Save the task
  4. Wait until the Task Management Task has run, and the EVMail task status has changed to STOPPED
  5. Edit the EVMail task and change the status from STOP_NOW to START_NOW
  6. Save the task
  7. Wait until the Task Management Task has run, and the EVMail task status has changed to STARTED

When EVMail is running and encounters a transient error, it will do the following:

  1. Generate a system_log warning message indicating that it has encountered a transient error
  2. Check the values for the new EVMail configuration parameters RUNTIME_WARN_NOTIFICATION_INTERVAL and RUNTIME_WARN_NOTIFICATION_COUNT
  3. Check the system log table and see how many warning messages have been created within the past RUNTIME_WARN_NOTIFICATION_INTERVAL minutes. If there are more than RUNTIME_WARN_NOTIFICATION_COUNT of them, it will create a new notification entry in the system log
  4. Check the RUNTIME_ERROR_NOTIFICATION_INTERVAL. If this is the first notification entry in the system log for this warning, in the last RUNTIME_ERROR_NOTIFICATION_INTERVAL minutes, send the email out to the ADMIN role users
  5. Note that EVMail will continue to run

Example:

  • RUNTIME_ERROR_NOTIFICATION_INTERVAL = 15 minutes
  • RUNTIME_WARN_NOTIFICATION_INTERVAL = 3 minutes
  • RUNTIME_WARN_NOTIFICATION_COUNT = 3
  • EVMail is set to run every minute

At 10:00 a.m. EVMail runs, and encounters a transient error as it cannot connect to the POP3 mailbox. A message is placed in the system_log table similar to the following:

<LOG_MESSAGE>EVMail Task had a WARN condition</LOG_MESSAGE>
<TASK_ID>700983</TASK_ID>
<TASK_TITLE>EVMail Task (Incoming email)</TASK_TITLE>
</LOG_MESSAGE>

ExtraView checks to see how many messages of this type, for this task_id exist in the system log table in the past 3 minutes - there is 1. 1 is less than 3 so ExtraView does not send any notification to the administrators.

At 10:01 a.m. EVMail runs again, and encounters the same error - a message is placed in the system_log table:

<LOG_MESSAGE>EVMail Task had a WARN condition</LOG_MESSAGE>
<TASK_ID>700983</TASK_ID>
<TASK_TITLE>EVMail Task (Incoming email)</TASK_TITLE>
</LOG_MESSAGE>

ExtraView checks to see how many messages of this type, for this task_id exist in the system log table in the past 3 minutes - there are 2. 2 is less than 3 so ExtraView does not send any notification to the administrators.

At 10:02 a.m. EVMail runs again, and encounters the same error - a message is placed in the system_log table:

<LOG_MESSAGE>EVMail Task had a WARN condition</LOG_MESSAGE>
<TASK_ID>700983</TASK_ID>
<TASK_TITLE>EVMail Task (Incoming email)</TASK_TITLE>
</LOG_MESSAGE>

ExtraView checks to see how many messages of this type, for this task_id exist in the system log table in the past 3 minutes - there are now 3. 3 is not greater than 3 so ExtraView does not send any notification to the administrators.

At 10:03 a.m. EVMail runs again, and encounters the same error - a message is placed in the system_log table:

<LOG_MESSAGE>EVMail Task had a WARN condition</LOG_MESSAGE>
<TASK_ID>700983</TASK_ID>
<TASK_TITLE>EVMail Task (Incoming email)</TASK_TITLE>
</LOG_MESSAGE>

ExtraView checks to see how many messages of this type, for this task_id exist in the system log table in the past 3 minutes - there are now 4. 4 is greater than 3, so we add a new message to the system log table:

<LOG_MESSAGE>EVMail Task had a transient error that persisted more than 3 times in 10 minutes.
<TASK_ID>700983</TASK_ID>
<TASK_TITLE>EVMail Task (Incoming email)</TASK_TITLE>
</LOG_MESSAGE>

ExtraView checks to see how many messages of this type for this task_id, exist in the system log table in the past 10 minutes - we have 1, so we need to send an email to all ADMIN users.

At 10:04 a.m. EVMail runs, and encounters the same error - a message is placed in the system_log table:

<LOG_MESSAGE>EVMail Task had a WARN condition</LOG_MESSAGE>
<TASK_ID>700983</TASK_ID>
<TASK_TITLE>EVMail Task (Incoming email)</TASK_TITLE>
</LOG_MESSAGE>

ExtraView checks to see how many messages of this type, for this task_id exist in the system log table in the past 3 minutes - there are now 4. 4 is greater than 3, so a new message is added to the system log table:

<LOG_MESSAGE>EVMail Task had a transient error that persisted more than 3 times in 10 minutes.
<TASK_ID>700983</TASK_ID>
<TASK_TITLE>EVMail Task (Incoming email)</TASK_TITLE>
</LOG_MESSAGE>

ExtraView checks to see how many messages of this type for this task_id, exist in the system log table in the past 10 minutes - there is 1, so ExtraView will send an email to all ADMIN users. Even if the transient error persists ExtraView only sends out warning emails every 10 minutes. If your EVJ.log shows errors similar to:

2012-10-30 13:45:54 [ ERROR] EVMT: EVMail Task (Incoming email) Mailbox Authentication failed - check your MAILBOX_USER and MAILBOX_PASSWORD
2012-10-30 13:45:54 [ ERROR] Exception = javax.mail.AuthenticationFailedException: Command is not valid in this state.
javax.mail.AuthenticationFailedException: Command is not valid in this state.

Check to see if the POP3 account is on an Exchange2010 server. If so, the problem is likely due to the fact that the Exchange POP is expecting encrypted credentials. To resolve your email administrators will need to run the following command in an Exchange shell which allows Exchange POP to use plain text credentials:

Set-PopSettings -LoginType PlainTextLogin

Then restart the POP3 service and the problem should be resolved.

Multiple EVMail Tasks

It is possible to configure multiple EVMail tasks, each with their own configuration. If you configure this on a single application server, then all the mail connections must either be secure (using POP3S) or not secure (using POP3). If there is a requirement to have mixed secure and non-secure servers, then you should set up a cluster of application servers, and then different servers may be configured to be secure or non-secure.

Technical Note on Incoming Emails with Attachments

There are three possible ways in which attachments to incoming emails can be handled. The first type is handling attachment parts or non-body parts of the incoming email. In general, anything that is attached to the incoming email should be uploaded to the ExtraView issue as a file attachment. The second type is when the body of the email message is not copied to a field on the ExtraView issue, but is instead uploaded as a file attachment to the ticket. This happens automatically if the body of the message itself is greater than 512kb in size. The third type is when the incoming email message itself is attached to the ExtraView issue. This will occur, through parameter settings, or encountering a message that cannot be processed for some reason.

  1. The part disposition is Part.ATTACHMENT

    Incoming emails processed by EVMail that have their own attachments - those files are always attached to the ticket.

    contentType.toLowerCase() = image/gif; name="ali's.gif" (the BODY is empty)

  • The part disposition is Part.INLINE

    Incoming emails processed by EVMail sometimes have inline attachments. These are often images in the user's signature, inline images within the email body or something similar to "this email has been checked by Virus Scanner".

    contentType.toLowerCase() = image/jpeg; name="businesscard.jpg" (the BODY is empty)

    These are only attached to the ticket if the EVMail behavior setting named EVMAIL_INCLUDE_INLINE_ATTACHMENTS is set to YES and a filename and content type are present. Otherwise, if content type is text, the text is appended to the email body. This setting defaults to YES, to not lose anything, but if your preference is not to have what are often just logos attached to issues, you can change this behavior setting to a value of NO.

  1. The part disposition is null

    If the incoming body of the email message exceeds a size of 512kb, ExtraView will NOT put the message body in the description/comments field, but will attach the email message to the issue and insert a line of text in the issue, indicating "see attachment <attachment filename> for body of email."

    contentType.toLowerCase() = text/plain; charset=utf-8; format=flowed (this has a BODY)
    contentType.toLowerCase() = text/html; charset=utf-8 (the BODY is empty)
     

  2. In all cases, and in addition to any other attachments added to the issue, there is a behavior setting named EVMAIL_ATTACH_EML. When this is set to a value of YES, the source text of the incoming email is also attached to the issue, as an .eml type file
  3. If EVMail receives a badly formed email message for some reason, and it cannot be processed, it is attached to the issue that is created, as opposed to throwing it away.