evmail

Processes responses emailed to ExtraView

SYNOPSIS

evmail [-n] [-r]

DESCRIPTION

With the inception of ExtraView 6.1, this command has been redeveloped as an internal, server-based ExtraView task that resides within the administration user interface. It is recommended that you use the new method for future development, although for backwards compatibility, the evmail CLI command will remain functional.

This command will process email messages that were sent to either create a new issue or in response to an ExtraView email notification. The body of the email is typically entered into the DESCRIPTION field of the issue created. An email message sent in response to an ExtraView email notification will be added into the COMMENTS or other field of the issue that triggered the initial notification. In addition, other fields may have values set with this command, such as setting the status of an issue, or setting an assigned to user. A reply may be sent to the submitter of the email, containing verification of the mail they sent.

The evmail utility can be installed on the same server as the ExtraView application, on the POP3 email or any other server on your network. Normally, this command will be setup as a job on a UNIX-based server, or as an AT command on Window-based server. External to ExtraView, you must have a POP3 mail server, and a dedicated POP3 mail account.

Attachments to email messages will be added as attachments to the issue being created or updated.

The -n flag stops ExtraView from sending mail, on both insert and update operations.

The -r flag is used to send a reply to the sender of the email received by ExtraView. Typically this is an acknowledgement of their submission of a new issue. Email is only sent as a reply if the email "from" and the email "to" addresses are different to avoid recursive, spoofed emails. The email body is defined in the evconfig.txt file, within the section named REPLY_TEMPLATE.

If the evmail command fails for any reason when it attempts to update the ExtraView database, an email reply is sent to the submitter, giving the reason for the failure. The email body is defined in the evconfig.txt file, within the section named SMTP_FAIL_MSG_FNAM.

The following table describes the entries that are used within evconfig.txt:

POP3_USER The name of the email account used as an address for ExtraView
POP3_PASSWORD The password of the email account
POP3_SERVER The address of the POP3 server
POP3_BODY_UDF This is the field into which the body of the email is placed, when a new issue is inserted into ExtraView. The field named DESCRIPTION is typically used to receive the text from the body of the incoming email
POP3_BODY_UPDATE_UDF This is the field into which the body of the email is placed, when an issue is updated. The default for this is the field named COMMENTS, but it can be set to any field with a display type of text area, log area or print text
POP3_fieldname A field name in ExtraView’s data dictionary to which data will be added. These fields can be inbuilt or user defined fields. Note that if such entries exist, then the Perl code in EV::Mail::Message.pm, must be altered to support this field and the value associated with it. Contact ExtraView support with questions about making changes within EVMailMessage.pm
EMAIL_SUBJ_REGEX The regular expression to be parsed on the subject line of the email. The first captured sub-expression is interpreted as the issue ID. EMAIL_SUBJ_REGEX is used to detect whether the message is an issue update and to determine the ID of the issue to be updated
DELIM_REGEX The delimiter used within the body of the email. Text following this delimiter is discarded.
REPLY_TEMPLATE This setting contains the filename of text that is returned to the submitter of the mail. The file may contain tags, i.e. references to fields within ExtraView. evmail will replace the tags with the values from the issue that was created or updated. For example, a tag __ID__ will place the issue number into the mail body, while a tag of __STATUS__ would enter the value of the field STATUS into the mail.
SMTP_FAIL_MSG_FNAM This setting contains the filename that contains a failure message that is returned to the submitter, if evmail could not complete its insert or update to ExtraView. Within the file, the tags named __REASON__ and __BODY__ can be used with the template as the placeholder for the specific failure reason

All actions taken by this command are logged to a file named mail_log.txt in the $EVDIR directory.

If the user name in the “from” address of the email matches the email address of a valid user in ExtraView, the ORIGINATOR field in ExtraView is set to that user.

If the email contains one or more file attachments of any type, the attachment(s) will be inserted into the issue.

To set up and configure evmail, you will need to identify the user role, business area and project that email-submitted issues will belong to. For example, you may decide that emails entered into ExtraView will be created as Customer Support issues, and will be entered into the system as if a user in the Customer role had signed in and created the issue - without the requirement of every potential Customer user needing a unique user ID within ExtraView.

To achieve this, create a Customer account, and sign in with that user name. Go through the process to add a new issue as this user. Identify the fields that are required, and the values that should be set for issues that are entered via email (e.g. Status = Submitted, Priority = Medium).

Once you have identified the fields and the values that you wish to set, the next step is to set those options in the evmail configuration file. If you are self-hosted, you will do this yourself. If you have chosen ExtraView’s ASP hosted solution, contact ExtraView support with this information and this will be set up for you.

The following is a sample configuration of evmail from the config.txt file.

SERVER = www.my_company.com/evj/ExtraView
POP3_USER = evmailuser
POP3_PASSWORD = my_password
POP3_SERVER = mail.my_company.com
EVMAIL_ID_REGEX = [ExtraView-(d+)]
DELIM_REGEX = ----Original Message-----
SMTP_SERVER = mail.my_company.com
SMTP_FROM = support@my_company.com
SMTP_CC = int-support@my_company.com
SMTP_FAIL_MSG_FNAM = tmpl8.txt
#
# tmpl8.txt might contain something like:
#
#__REASON__
#-------- Original Message --------
#__BODY__
#
# evmail will substitute EVs failure
# message for __REASON__, and the body
# of the email for __BODY__.
# required fields
# need to do reverse lookup
POP3_BODY_UDF = description
POP3_CATEGORY = QUESTION
POP3_CUST_SEVERITY = 6821
POP3_PRODUCT_NAME = MY_PROD
POP3_STATUS = SUBMIT
#POP3_ASSIGNED_TO = dcrane
POP3_ORIGINATOR = evmailuser
#POP3_SUBMITTED_YES = 8821
HB_SMTP_SERVER=mail.my_company.com
HB_FROM=evmailuser@my_company.com
HB_TO=leeann@my_company.com, donald@my_company.com