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 name and observe a screen similar to:

When configuring EVMail with Oauth2 connections, there is an appendix to this guide at OAuth2 Email Mailbox Settings to assist.

Basic Configuration

To configure EVMail, you will need a properly configured mailbox and you will need its username and password.  Depending on the MAILBOX_TYPE you will need additional information.  This varies with the different MAILBOX_TYPEs and is clearly laid out in the example properties that you see when you first enter the task editor screen.

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 issues will be created and you will not be able to update issues.

Note: The MAILBOX_USER value should never be the email address of an end 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 populate 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 of built-in fields or the List ID value of the User Defined Fields (i.e. the UDF_LIST_ID value), not the title of the field. You can find the List ID value by viewing the list of values for the field in the administration screen that updates and modifies the values.

You can use a similar technique to find the AREA_ID for the AREA field and the PROJECT_ID for the PROJECT field. Go to the administration screen for each of these fields and you will see a column on the screen with the ID for each of the fields.

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_ADDL_DELIMS_TEXT This setting is used in conjunction with the behavior setting named EVMAIL_DELIMITER_TEXT and the EVMail configuration setting EVMAIL_ADDL_DELIMS_HTML.  Together they provide additional controls on incoming email to the EVMail feature, to parse the email looing for the new content to include and to inhibit the repeated addition of older content of the emails.  This is typically seen when users reply to emails add simply append their new message to the thread of existing messages.  It is often desirable to only include the latest mail as an update to the ExtraView issue, and not to repeat existing, older comments.  These settings are only used when updating existing issues within the ExtraView database, and not used when new issues are being inserted.  The EVMAIL_ADDL_DELIMS_TEXT setting is used when the incoming email has a contentType of text/plain. Any number of delimiters may be specified, delimited within the settings with ||.

Example:

EVMAIL_ADDL_DELIMS_TEXT = delimiter string 1 || delimiter string 2 || delimiter string 3

Three delimiters are specified in the example, and the incoming mail is parsed looking for all occurrences of the three strings
EVMAIL_ADDL_DELIMS_HTML See EVMAIL_ADDL_DELIMS_TEXT above.  The principal difference is that the delimiter being parsed within the incoming email has a contentType of text/html.  Different email clients generate different delimiters and some experience with examining different email headers is required in order to be able to successfully determine the range of delimiters you expect.

Example:

EVMAIL_ADDL_DELIMS_HTML = <div style="border:none;border-top:solid #B5C4DF 1.0pt;

This delimiter string is often seen within Microsoft Outlook emails.
EVMAIL_ALLOW_HTML_MSG Valid values are YES, NO and PARSE. If this is not specified, the default value is PARSE. The behavior of the two properties named EVMAIL_ALLOW_HTML_MSG and EVMAIL_ALLOW_HTML_MSG_FAIL_TEMPLATE control 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.
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.  See the property EVMAIL_ALLOW_HTML_MSG for more information
EVMAIL_ATTACH_EML If this has a value of YES, a copy of the incoming email is attached as an .eml file to the issue that is created.  If the value is NO, no .eml file is attached to the issue.
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_HTML_UDF_ATTACHMENT_LINK Set this option to a value of YES if you want ExtraView to associate any attachments to the incoming email to the field set in EVMAIL_BODY_HTML_UDF
EVMAIL_BODY_HTML_UPDATE_UDF_
ATTACHMENT_LINK		 Set this option to a value of YES if you want ExtraView to associate any attachments to the incoming email to the field set in EVMAIL_BODY_HTML_UPDATE_UDF
EVMAIL_BODY_UDF_ATTACHMENT_LINK Set this option to a value of YES if you want ExtraView to associate any attachments to the incoming email to the field set in EVMAIL_BODY_UDF
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_UPDATE_UDF_
ATTACHMENT_LINK		 Set this option to a value of YES if you want ExtraView to associate any attachments to the incoming email to the field set in EVMAIL_BODY_UPDATE_UDF
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. If the CC list contains the email address set within the MAILBOX_USER property, it is not included within the EVMAIL_CC_UDF field
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.
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_PRIORITY_FIELD This is an optional property.  If this is set to a value that is a User Defined Field with a display type of Checkbox, then the following happens:

  • Incoming email headers are examined to see if there is a high priority flag set
  • If the flag is set, the User Defined Field checkbox is set to checked

Note that during the updating of an issue, the value assigned to this field is reset and set again according to the priority of the incoming mail that is being processed.
EVMAIL_RECORD_MATCHING_DATE This property works in conjunction with the property EVMAIL_RECORD_MATCHING_DATE_RANGE.  When processing incoming emails, if more than one matching issue is found, ExtraView looks at the date / timestamp of the incoming email.  This property is set with the value of a field with display type of DATE or DAY.  For example, you may use the TIMESTAMP or DATE_CREATED fields.  DATE_RANGE checking logic is then triggered with the value of the property EVMAIL_RECORD_MATCHING_DATE_RANGE
EVMAIL_RECORD_MATCHING_DATE_RANGE See EVMAIL_RECORD_MATCHING_DATE
EVMAIL_SENDER When set, this option will take the email address of the sender of the incoming email and store it within a field within the issue that is being inserted or updated.  The usage is:

EVMAIL_SENDER = SOME_TEXT_FIELD
or
EVMAIL_SENDER = SOME_USER_FIELD

This allows the user to view the field and determine who provided the last update to the issue via email, as opposed to the user who last updated the issue with the user interface of ExtraView.
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_SUPPRESS_HEADER This configuration option allows their administrator to remove specific lines from the header of the incoming mail, before the mail is inserted into a field within ExtraView.  The remaining text is inserted into the destination field defined with EVMAIL_BODY_UDF.  The header lines removed begin with the following strings and they must appear within the incoming mail before the occurrence of the EVMAIL_DELIMITER_TEXT contained within the email body:

From:
To:
Send:
Subject:
Date:

Only header lines that begin with these strings are removed.  There must not be blank lines between the header lines and they must all be followed within the mail body by the EVMAIL_DELIMITER_TEXT.  If the mail does not contain a the expected value for EVMAIL_DELIMITER_TEXT, then this configuration option is ignored.  This implies that the header information is not removed when creating a new issue within ExtraView, and is only operable when updating issues. The default value for this property is NO.  To enable the property, set a value of YES.
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. The email address within the property named MAILBOX_USER is not included in the values of the EVMAIL_TO_UDF property. 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.
EXCHANGE_URL When the MAILBOX_TYPE is EXCHANGE, this is the address of the Exchange server to which you are connecting.  This is required when you have a MAILBOX_TYPE of EXCHANGE
IGNORE_SUBJECT.xx The optional IGNORE_SUBJECT setting can be used to specify one or more strings to detect within the subject line of the incoming email, to determine whether to ignore and skip the entire email message from being processed. The string text configured in this setting is case-sensitive and be matched exactly anywhere in the subject line of the incoming email message. Note: For a single text, use simply IGNORE_SUBJECT; for multiple texts, use IGNORE_SUBJECT with a unique postfix for each entry, such as a number.​For example to configure multiple entries to be ignored:

IGNORE_SUBJECT.1 = Mail Delivery Failure
IGNORE_SUBJECT.2 = Automatic reply:
​IGNORE_SUBJECT.3 = Free offer
MAILBOX_PROCESSED_EMAIL_FOLDER This setting works only when you set the MAILBOX_TYPE to either EXCHANGE or IMAP.  Other mailbox types are not supported with this property.  When configured with the name of a folder on your local file system, incoming mail that has been processed is copied to a file within this folder as opposed to being deleted after processing.  If this is not specified with a valid folder name on your server, the incoming mail is deleted after processing
MAILBOX_TYPE This property may have one of four values: POP3, EXCHANGE, OWA or IMAP.  These correspond to the mail server interface to which you are connecting. OWA is largely deprecated and used to connect to Exchange servers prior to 2007.  When using a setting of OWA, you should also set the OWA_DESTINATION, OWA_DOMAIN, OWAFBA_PATH, OWA_ISA and OWA_PATH properties.  With the other MAILBOX_TYPE settings, you will typically set the MAILBOX_PASSWORD, MAILBOX_PORT, MAILBOX_SECURE, MAILBOX_SERVER and MAILBOX_USER settings
MAILBOX_PASSWORD The password associated with the MAILBOX_USER
MAILBOX_PORT The port number of the mailbox server
MAILBOX_SECURE This should have a value of NO or YES depending on the way your mail server is configured
MAILBOX_SERVER The domain address or IP address of the mail server
MAILBOX_USER The user ID of the mail server
OWA_DESTINATION The address of the OWA server
OWA_DOMAIN The Microsoft Windows domain to which the server belongs
OWA_FBA_PATH The Microsoft Windows path to owaauth.dll
OWA_ISA Usually this is set to true
OWA_PATH This should be Exchange
PARSE_EMAIL
PARSE_VALUE_DELIMITER
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 = $ 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++

The PARSE_VALUE_DELIMITER is an optional property which has a value of {field_title}.  This is used in situations where the incoming email only has one or more HTML parts, and there are no plain text parts.  In this situation it is not possible to parse the mail looking for a title which follows the property name and ends at the end of line within the email as the title will be embedded within one or more HTML tags and there may not be any end of line character.  To handle this situation, the title should be embedded within braces {}.  EVMail will look for the braces and is then able to extract the title from within the PARSE_FIELD properties.  For example:

PARSE_VALUE_DELIMITER={}
​PARSE_FIELD.STATUS = {Status}
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.

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.  This user should be a NAMED user, not a CONCURRENT licensed user
  • 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 with a user who only has a GUEST role, updates to issues are not permitted.

Which Issue is Updated Via EVMail?

The logic to locate which issue to update with a received mail is a multi-step process, as follows.

    1. First, the EVMAIL_ID_REGEX parameter is used to attempt to identify a unique ExtraView issue ID in its subject line
    2. Second, the MESSAGE_ID within the message header is examined and used to try and find a matching ExtraView issue. This is accomplished if the configuration parameter EVMAIL_MESSAGE_ID points to a TEXTAREA field to store the MESSAGE_ID.  This field must be present on both the ADD_PROBLEM and EDIT_PROBLEM layouts and must be writable, although you can hide the field.
    3. If more than one matching issue is found, ExtraView next looks at the date of the incoming mail.  This logic is configured with the definition of the EVMAIL_RECORD_MATCHING_DATE parameter within the task configuration.  The field identified with this parameter must have a display type of DATE or DAY.  For example, you can use the inbuilt TIMESTAMP or DATE_CREATED fields
    4. DATE_RANGE checking logic is then triggered with the configuration value of EVMAIL_RECORD_MATCHING_DATE_RANGE. Supported formats and their meanings are:
      1. SYSDATE-2 means between SYSDATE and 2 hours or 2 days earlier.
      2. 0-2 has the same meaning as SYSDATE-2. Zero is interpreted as SYSDATE
      3. 1-3 has the meaning of between 1 hour earlier than the SYSDATE and 3 hours earlier than the starting point, or a DAY earlier than the SYSDATE and 3 DAYS earlier than the starting point. Examples:
        • Both the DATE field and DATE RANGE field are defined:
          • The one with latest DATE value withing the DATE_RANGE is chosen
          • No issue is found if there are no results within the DATE RANGE.
        • The DATE field is defined but the DATE RANGE field is not:
          • The issue with the latest DATE value is chosen
        • Both the DATE and DATE RANGE fields are not defined or only the DATE RANGE field is defined:
          • No issue is selected
    5. ExtraView uses SUBJECT line matching if none of the above steps work, and if EVMAIL_SUBJECT_LOOKUP = YES is defined within the configuration.

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.

EVMail and HTML

With the configuration options EVMAIL_BODY_HTML_UDF, EVMAIL_BODY_HTML_UPDATE_UDF and log area fields configured to use HTML, incoming emails via EVMail will be treated as HTML, and the contents placed in the corresponding fields.  If the source of the incoming email is pure HTML, then the presentation of the data within the fields will look extremely similar to the source data.  If the source of the data is an email client such as Microsoft Outlook, there may be differences in the presentation which cannot be reconciled.

The major differences occur for these reasons:

      • Microsoft Outlook typically uses Microsoft Word as its internal editor and this does not produce standard HTML.  Particularly, there are often formatting tags within the contents that have no equivalent within HTML.  Similarly, Outlook often uses Cascading Style Sheet (CSS) classes that cannot be interpreted within an HTML browser
      • If the source of the data relies on CSS styles and these are not transmitted with the email, ExtraView has no way of understanding what the style might be

The result is that underlying text within the email will be displayed, but sometimes will not have the correct formatting.

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 issues 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 covers instructions on how to connect ExtraView to a POP3 mail server configured with SSL, i.e. POP3S.  It is highly recommended that you configure POP3S rather than POP3.  This configuration is only required if you have a self-signed SSL certificate.

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: changeitYou will then see the something like this:
        Keystore type: jks
        Keystore provider: SUNYour 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.cerEnter default keystore password: changeitOwner: 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 a connection using Exchange Web Services (EWS):

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 or POP3S 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 issue. 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 issue.

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

    2. 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 issue 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.

    3. The part disposition is nullIf 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)

    4. 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
    5. 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.