EditHow to setup creation of incidents from emails
The creation of incidents from emails is done by a program called ESI.Octopus.MailIntegrationApp.exe. This program is a command-line application that reads the content of a mailbox and creates one incident per email found in the mailbox.
EditESI.Octopus.MailIntegrationApp.exe parameters
The program takes 3 parameters:
/Login : Username of an Octopus account that will be used to create the incidents. This name will be visible in the incident history as the incident creator. You can create a new Octopus account for this.
Example:
First Name: Mail, Last Name: Integration
/Password : Password for the account mentioned above.
/ConfigFilePath : A file path to a configuration file. The next section describes how to prepare the configuration file.
EditConfiguration file for the creation of incidents
The configuration file is a text file that contains the information about the mail server, mailbox to use and other settings required by the program. This file uses the XML format.
Warning
Before you start creating the configuration file, please note that you must be very careful not to break the file format by modifying the tags or the file structure. A single missing or extra “/ “or “<” or ”>” can render the file unusable.
Make also sure the values you specify are valid. Do not leave extra spaces before or after the values.
In case of an error in the configuration file the program will halt without any bad side effect. However, the program is not verbose in the way it report errors so errors could be difficult to find.
A careful verification of the values is recommended before you run the program.
- Open the following Notepad file: Email Integration
- In the
<serverName>SERVER</serverName> section, replace SERVER by the name of your email server. - In the
<userName>MAILBOX</userName>section, replace MAILBOX by the name the account on the mail server. Normally this does not include the domain part of the public email address. For example, you would indicate “newincident” here, not “newincident@mycompany.com”. - In the
<password>PASSWORD-CLEAR-TEXT</password>section, replace PASSWORD-CLEAR-TEXT by password for this account. - In the
<incidentFallbackSiteName>FALLBACK-SITE<incidentFallbackSiteName> section, replace FALLBACK-SITE by 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 he/she has no site, the program will use the site indicated here. - In the
<incidentFallbackUserLogon>FALLBACK-USER</incidentFallbackUserLogon> section, replace FALLBACK-USER by the windows username of an existing Octopus user (a technician of not). This must be the same value as it is registered in the Windows Username field of the user in Octopus. If ever an email is received form an email address that is not recognized by Octopus, the system will use the account indicated here as the incident’s “Requested By” and “User”. - In the
<incidentSource>INCIDENT_SOURCE</incidentSource> section, replace INCIDENT_SOURCE by the name of the source you want to use. Typically you would indicate “Email” in this setting. - Save the file in “c:\program files\octopus\” with that “.xml” files extension. For instance “email-integration.xml”
Run ESI.Octopus.MailIntegrationApp.exe for the first time
To test MailIntegrationApp, do the following.
- Send an email to the account that will receive the emails
- Open a command-line window
- Enter this command and press ENTER: c:\
- Enter this command and press ENTER: cd c:\program files\octopus\
- Enter this command by providing the correct values for the 3 parameters and press ENTER: ESI.Octopus.MailIntegrationApp.exe /Login: loginname /Password:password /ConfigFilePath: path
- The program will run for several seconds and will terminate.
- Go to Octopus and open the “New” incidents list to see the new incident.
Automate ESI.Octopus.MailIntegrationApp.exe
MailIntegrationApp will not monitor or watch the mailbox. When you run MailIntegrationApp, it read the mailbox once, it creates the incidents and it terminates. Therefore, you will need to automate the execution of MailIntegrationApp. To do so, all you have to do is create a Windows Scheduled Task to execute this program every 5 or 10 minutes. If you need assistance creating the scheduled task, contact us at support@octopus-itsm.com.