MailIntegration - Create Incidents or Events from Emails

Table of contents

Related articles

Introduction

MailIntegration (ESI.Octopus.MailIntegrationApp.exe) is a program used in Octopus to create new requests (incidents or events) or update the activities of a requests received via email. The program needs to be automated using the Windows Task Manager.

If you want to create incidents from a surveillance system (System Center Operations Manager 2007, for example), please consult the Create events from emails section. 

What you need to know:
To use MailIntegration, you need a dedicated email account and you need to make sure that the POP3 protocol is enabled on your email server.

Important:
From version 3.8 and on, there is a new parameter to add to the command line to indicate to MailIntegration which team must be updated. See the Execute MailIntegration from a command line section for more details.

How MailIntegration Works

When MailIntegration is started, it will read the mailbox to see if it contains any new messages. If it does, the program will validate if the email is a new incident, an event or meant to update an activity in an existing request. 

The method used by Octopus to "recognize" an email is the following. Octopus reads the email subject and if the request number is found in a specific format, it will update the request, otherwise it will create a new incident/event.

In the image bellow, the first part represents the format that Octopus looks for to update a request:

  • the communication type in between square brackets
  • sometimes followed by the name of the DB or the team name
  • the request number


In the case where it is a new email, MailIntegration will create a new incident or event in Octopus. The email subject will be the incident/event subject and the email body will be placed in the detailed description. For an incident the sender will be tagged at the requester/user. If the email of the sender is not recognized by Octopus, the incident requester/user will be the system user previously defined (Fallback user). 

If the email concerns an existing request, an activity will be added to the request containing the name of the sender, as well as the date and time of the activity in Octopus.

Email processed by MailIntegration will then be deleted. This is the standard behavior for the POP3 protocol. To keep a copy of received mails, you will have to configure your system in one of the following way, depending on the Mailing system used. We invite you to contact your mail administrator to decide which is right for you.

  • Use a distribution list that delivers email in a mailbox meant for MailIntegration and a mailbox meant for archival.
  • Configure a server-side mail delivery rule that will also send email received in a mailbox meant for archival.
  • Configure a server-side mail copy rule that will also copy email received in a folder meant for archival.

Please note that it is not possible to create a service request directly from MailIntegration.
 

Prerequisites

Email Account

Have an email account that is dedicated to Octopus. To configure MailIntegration, you need the following information:

  • the complete address of the account
  • the name of the user of the account
  • the account password
  • the email server name

POP3 Protocol

NOTE: the Fall 2012 version is a prerequisite to the use of the SSL secure mode

The only supported protocols for the MailIntegration program are POP3 and secure mode POP3 (SSL). The protocol to use needs to be activated on the email server that will be used.

If you want to use POP3 in secure mode (SSL), you have to make sure the machine executing MailIntegration recognizes the authenticity of the certificate used, either by using a trusted certificate authority, or by locally installing the server's self-signed certificate.

Test the POP3 Protocol

MailIntegration will not function if the protocol test does not work, you will find the information to do this test in the MailIntegration - Testing the POP3 connection page. 

System User

A system user should be designated to associate to incidents when the sender's email is not recognized by Octopus.

This user could also be configured to run the Windows task. For more information on the subject, see the Octopus System Account article.

Attachment Directory

In order to use MailIntegration, the network path for the attached files needs to be configured in Octopus. (Tools menu > Options > 3rd section - Important general options > Network directory containing the attached files).

In case of a problem an event is automatically created

It is important to note that in case of issues with MailIntegration, Octopus will create an event with instructions on how to resolve it. For this reason, before activating MailIntegration, we recommend to ensure members of your Service Desk have subscribed to the New Event notification. 

  • (File menu > My notification preferences... > New Event)
  • the permission Access the Event Management module is also required

Octopus displays a specific content when an error with an email message is encountered.

When a problem is detected, the event management shows a new entry that contains the original message blocking the application.

VISUAL EXPLANATION

 

The message can be seen in the "Attached Files" tab.

VISUAL EXPLANATION

Attached Files

MailIntegration will do the same when an already existing event gets a new activity.

In case of an infrastructure outage detection, Octopus also creates an event but this time, it displays a message that contains the issue's source.

VISUAL EXPLANATION

Infrastructure issue

The configuration file will be attached(without passwords, if required) in an .XML format.

VISUAL EXPLANATION

Infrastructure issue - XML file

Octopus will continue to add additional activities as long as the issue is still occurring.

VISUAL EXPLANATION

Additional activities

Furthermore, once the MailIntegration issue gets resolved, Octopus then proceeds to automatically mark the event as processed.

VISUAL EXPLANATION

Automatic closure

Using the MailIntegration Program

MailIntegration is a command line type program (DOS). It is designed this way to be easy to automate (the Automate email updates in Octopus section describes how to automate the execution of MailIntegration). 

  • The complete name of the program is: ESI.Octopus.MailIntegrationApp.exe
  • It is located in the local Octopus folder (C:\Program Files\Octopus) or in (\%homepath%\AppData\Local\Octopus)
  • Example of the folders where Octopus can be found:
    • For Windows 7: C:\Users\slevesque\AppData\Local\Octopus
    • For Windows XP: C:\Documents and Settings\Slevesque\Local Settings\Application Data\Octopus

Parameters

There are 6 available parameters to execute MailIntegration, of which 4 are mandatory:

Mandatory Parameters

  • /Login:
    • Octopus user name
      • This account will be used to create the incidents and will be visible in the history tab. It is better to use a dedicated account for this program. (Example: Mail Octopus)
  • /Password:
    • Octopus password
  • /Team (from version 3.8 only)

    • The number of the team to be updated. By default, the IT team is 1

  • /ConfigFilePath:
    • Path to the configuration file.

The next section explains how to prepare the configuration file.

Optional Parameters

  • /LogFilePath:
    • To replace the path to the log file. By default, the file is named MailIntegration.log and is located in the Octopus folder. If you move the file to another folder, the folder needs to exist (the system cannot create the folder). Furthermore, the path needs to contain the file name.
      • Example:/LogFilePath:C:\LogFiles\MAILINTEGRATION.log
  • /Debug:
    • In cases where we need to troubleshoot an issue, our Service Center may ask to have this parameter added to create a RAW message for each message received and help to investigate the problem. Note that if you activate this parameter the Octopus folder may get large amount of RawMessage.txt files and will need to be cleaned up regularly.

Operations Log File

Files generated by the execution of the MailIntegration program:

  • MailIntegrationApp.log:
    • Operation log file generated each time the program is executed
  • RawMessage.txt:
    • Content of the email in raw text in case of problem or at the request of the Octopus Service Center by adding the /DEBUG parameter 

The files are created in the same folder at the executable "ESI.Octopus.MailIntegrationApp.exe". Furthermore, these files can be requested to troubleshoot a MailIntegration issue.

Configuration File (XML)

The configuration file is a text file containing the information on the mail server, the username and password of the mailbox to use, as well as other parameters required by the program. This file uses the .XML format. The following section explains the 2 formats available for the .XML file, one for POP3 and the other for SSL. 

NOTE

Be careful not to change the format of the information contained in the file. As any "/" or "<" missing in the structure can render the file unusable. Make sure that the specified values are valid. Do not leave any empty spaces before or after the values. 

In case of errors with the configuration, the program will stop working and an Event will be created in Octopus with details on the problem.

To view the information contained in the file, you can use a software like Internet Explorer. And to edit, we recommend Notepad or Notepad++.
Accents are not supported in the XML file. You need to replace the accents with the corresponding HTML code Entity

Example: 

 must be replaced by



To find the HTML Entity accent correspondence, consult the following Correspondence Table.

Incident creation using a XML POP3 file

Open the following file in Notepad:

<?xml version="1.0" encoding="utf-8" ?> 
<MailIntegration>
  <messageProcessorTypeName>ESI.Octopus.MailIntegration.EndUserIncidentMailMessageProcessor, ESI.Octopus.MailIntegration</messageProcessorTypeName> 
  <server> 
    <gatewayTypeName>ESI.Octopus.MailIntegration.SidePopMailboxGateway, ESI.Octopus.MailIntegration</gatewayTypeName>
    <serverName>SERVER</serverName> 
    <port>110</port> 
    <useSsl>false</useSsl> 
    <userName>MAILBOX</userName> 
    <password>PASSWORD-CLEAR-TEXT</password> 
  </server> 
  <incidentFallbackSiteName>FALLBACK-SITE</incidentFallbackSiteName> 
  <incidentFallbackUserLogon>FALLBACK-USER</incidentFallbackUserLogon> 
  <incidentGroup>ASSIGNED_GROUP</incidentGroup> 
  <incidentSource>Courriel</incidentSource> 
  <ignoredAttachments></ignoredAttachments> 
</mailIntegration>

The highlighted sections need to be configured. These tags are explained in the following section.
 

Explanation of the Tags

  • <ServerName>SERVER</ServerName>:
    • Name of email server.
      • Replace SERVER with the name of the email server
  • <UserName>MAILBOX</UserName>:
    • Username of the mailbox account.
      • Replace MAILBOX with the user account name used to authenticate. Normally this does not include the domain part of the public email address. For example, you would indicate “newincident” here, not “newincident@mycompany.com”.
  • <Password>PASSWORD-CLEAR-TEXT</Password>:
    • Mailbox account password
      • Replace PASSWORD-CLEAR-TEXT with the password of the mailbox account.
  • <IncidentFallbackUserLogon>FALLBACK-USER</IncidentFallbackUserLogon>:
    • Generic username to be used in cases where the email address of the sender is not recognized by Octopus. 
      • Replace FALLBACK-USER by the windows username of an existing Octopus user. This must be the same value as recorded in the Windows Username field of the user's file in Octopus. If an email is received form an address that is not recognized by Octopus, the system will use the fallback user indicated here as the incident’s “Requestor” and “User”.
  • <IncidentFallbackSiteName>FALLBACK-SITE<IncidentFallbackSiteName>:
    • This tag will be mandatory only when the site is mandatory in Octopus. (Tools menu > Options > section 3 - Important general options > Visible and required fields)
      • Replace FALLBACK-SITE with the name of a site that exists in Octopus. When the program runs it tries find the Octopus user based on the email address of the sender. If that sender is not recognized or if the user has no site, the system will use the site indicated here. If the site is not mandatory in the options, this tag can be removed.
  • <IncidentSource>INCIDENT_SOURCE</IncidentSource>:
    • Indicates the incident creation source
      • Replace INCIDENT_SOURCE by "Email". Another source could be used, however it needs to be already configured in Octopus to work.
  • <IncidentGroup>ASSIGNED_GROUP</IncidentGroup>:
    • This tag is not mandatory. It indicates the name of group that differs from the service center during the incident creation. This option is usually used if mailintegration is configured for more then one mailbox
      • Replace ASSIGNED_GROUP by the name of the group that would be assigned to requests from this mailbox. To assign requests to the service center by default, remove this line from the XML file.
  • <IgnoredAttachments></IgnoredAttachments>
    • This tag is not mandatory. It is used to ignored some attached files. For example: a logo.
      • Indicate a comma-separated list of files to be ignored, including the extension.
  • <CreateNewRequests>True</CreateNewRequests>
    • This tag will determine if new incidents can be created from an email message that is not linked to an active request. 
    • If the new request creation is deactivated, the system will respond to the user with an email message based on a template that can be found in Tools > Options > Other messages section  -  Automatic reply for denied request creation by MailIntegration.
  • <IncludeRawMessageAsAttachment>True</IncludeRawMessageAsAttachment>
    • This tag controls if a copy of the email message in EML format will be attached to the created incident.

Once the tags have been configured with the proper information, save the file to the Octopus folder with the .xml extension. For example "Email-Integration.xml"

Using a POP3 SSL

Open the following file in Notepad:

<?xml version="1.0" encoding="utf-8" ?>
<mailIntegration>
  <messageProcessorTypeName>ESI.Octopus.MailIntegration.EndUserIncidentMailMessageProcessor, ESI.Octopus.MailIntegration</messageProcessorTypeName> 
  <server> 
    <gatewayTypeName>ESI.Octopus.MailIntegration.SidePopMailboxGateway, ESI.Octopus.MailIntegration</gatewayTypeName>
    <serverName>SERVER</serverName> 
    <port>995</port> 
    <useSsl>true</useSsl> 
    <userName>MAILBOX</userName> 
    <password>PASSWORD-CLEAR-TEXT</password> 
  </server> 
  <incidentFallbackSiteName>FALLBACK-SITE</incidentFallbackSiteName> 
  <incidentFallbackUserLogon>FALLBACK-USER</incidentFallbackUserLogon> 
  <incidentGroup>ASSIGNED_GROUP</incidentGroup> 
  <incidentSource>Courriel</incidentSource> 
  <ignoredAttachments></ignoredAttachments> 
</mailIntegration>

The sections in yellow are the additional ones used with SSL. These new tags are explained in the following section.

 

Explanation of the Additional Tags

Refer to the previous section for the description of the tags common to both files.

  • <UseSsl>true</UseSsl>:
    • When set to "TRUE", the system will use the SSL protocol
  • <Port>995</Port>:
    • Indicates the port to use.

Create events from emails

Copy the following file to your text editor:

<?xml version="1.0" encoding="utf-8" ?>
<mailIntegration>
  <messageProcessorTypeName>ESI.Octopus.MailIntegration.EventMailMessageProcessor, ESI.Octopus.MailIntegration</messageProcessorTypeName>
  <server>
    <gatewayTypeName>ESI.Octopus.MailIntegration.SidePopMailboxGateway, ESI.Octopus.MailIntegration</gatewayTypeName>
    <serverName>SERVER</serverName>
    <port>110</port>
    <useSsl>false</useSsl>
    <userName>MAILBOX</userName>
    <password>PASSWORD-CLEAR-TEXT</password>
  </server>
  <group>GROUP</group>
  <assignee>ASSIGNEE</assignee>
</mailIntegration>

The sections in yellow are the ones that need to be configured. These tags are explained in the next section. Then save the file in the Octopus folder with the ".xml" extention file. For example "event-email-integration.xml"

Explanation of the Tags

  • <ServerName>SERVER</ServerName>:
    • Name of email server.
      • Replace SERVER with the name of the email server
  • <UserName>MAILBOX</UserName>:
    • Username of the mailbox account.
      • Replace MAILBOX with the user account name used to authenticate. Normally this does not include the domain part of the public email address. For example, you would indicate “newincident” here, not “newincident@mycompany.com”.
  • <Password>PASSWORD-CLEAR-TEXT</Password>:
    • Mailbox account password
      • Replace PASSWORD-CLEAR-TEXT with the password of the mailbox account.
  •  <Group>GROUP</Group>
    • This tag is used to designate the group in charge of events
      • Replace GROUP with the name of the group assigned to events
  • <Assignee>ASSIGNEE</Assignee>
    • This tag allows to assign events directly to an Octopus user in the case where only one person takes care of events
      • Replace ASSIGNEE with the Windows username of the technician assigned to events. This tag can be left empty (<assignee></assignee>)

Execute MailIntegration from a Command Line

NOTE: Before running tests with MailIntegrationApp, it is recommended to test the POP3 connection to the server using the following procedure: Testing the POP3 connection


To run the MailIntegration executable file, open a DOS prompt and go to the Octopus folder. Then use the following command line:

Before 3.8

ESI.Octopus.MailIntegrationApp.exe /login:system /password:octo /ConfigFilePath:C:\Program Files\Octopus\email-integration.xml

After 3.8

ESI.Octopus.MailIntegrationApp.exe /login:system /password:octo /team:1 /ConfigFilePath:C:\Program Files\Octopus\email-integration.xml



To test MailIntegration for the first time, follow these steps:

  1. Send an email to the Octopus dedicated mailbox
  2. Open a DOS prompt
  3. Go to the Octopus folder
  4. Enter the following command along with the proper values for the 3 parameters and do ENTER:
    ESI.Octopus.MailIntegrationApp.exe /Login:OctopusUserName /Password:OctopusPassword /ConfigFilePath:(path to XML file)
    
    OR
    
    ESI.Octopus.MailIntegrationApp.exe /Login:OctopusUserName /Password:OctopusPassword /team:TeamNumber /ConfigFilePath:(path to XML file)
    

    The program will work for a few seconds and finish.

  5. Open Octopus and check the incidents listed under "New" to find the one just created.

Automate Email Updates in Octopus

MailIntegration only runs once at a time. Therefore, the execution of MailIntegration needs to be automated to check the mailbox regularly. 
Refer to the Windows Scheduled Tasks article to automate the reception and updates of email.

X
Help us improve our articles








Help us improve our articles