MailIntegration - Troubleshooting

SHOW ALL CONTENT

Table of contents

Dépannage
MailIntegration Office365 365 Microsoft365

Introduction

The MailIntegration program (ESI.Octopus.MailIntegrationApp.exe) allows you to receive emails in Octopus to:

  • Create an incident
  • Create a service request
  • Create an event
  • Update an existing request by adding an activity

For more information see the article MailIntegration - Create Incidents or Events from Emails 

IMPORTANT NOTE for Office 365 box users:

Basic authentication mode is being retired by Microsoft, it will no longer be available as of October 1, 2022, to ALL tenants (it may already be disabled in yours).

To avoid any disruption of service with MailIntegration, you should definitely switch to Azure authentication.

See the article on the following procedure to switch to Azure authentication Using the OAuth authentication mode on Office 365. 

Octopus provides a tool that allows you to view and manipulate the configuration of the MailIntegration application. See the article MailIntegration Configuration Tool for more details.

Troubleshooting

It is possible that errors occur during its execution.

When email processing stops working, it is recommended that the following steps are followed to assist you in the analysis:

1- Event Management

When MailIntegration is able to run and an error occurs, an event with more details is generated.

  • Blocked email (.EML file)
    • If in the event, there is an .EML file in the attachment tab, it is possible that this email blocks the execution of MailIntegration.
    • You have to remove this email from the inbox manually and observe if the other emails are processed correctly.
    • It is recommended to send this .EML file to Octopus support for analysis and to indicate on which event number it was generated.
  • More frequent error messages

    • An event can display messages in the activity.

    • If the error is able to resolve itself automatically, such as a temporary unavailability on the mailbox, a message "Successful processing, closing the event" will be added as an activity and the event go to the "Processed" state automatically.

    • In cases where the event does not automatically resove, here are the more common error messages and probable causes:

       

      Messages Probable Causes

      "Unable to connect to outlook.office365.com:995".

      A connection attempt failed because the connected party did not respond appropriately after a certain period of time or an established connection failed because the connecting host did not respond 52.66.88.133:995      		 The POP 3 server is not allowed for this IP address or the network blocks the connection to the POP3 server.
      "The BeginRead method cannot be called when another read operation is pending."

      This may indicate that a concurrent or overlapping run has occurred.
      Access to the shared directory (YourServer\OctopusAttachments) is denied or the directory does not exist.

      Access to the attachment directory of the Windows user running the MailIntegration task is missing.

      This path is set (by Team) in Tools ->Options.
      The Site name in the configuration file is invalid.

      The Site entered in the XML file is not valid

      "An error occurred while authenticating against mail server."

      • ERR Logon failure: unknown user name or bad password.

      This indicates a problem authenticating to the mailbox (password, for example).

      1. Access the outlook site (https://outlook.live.com/owa/) in private browsing

      2. Authenticate with the user and same password indicated in the XML file.

      This information is populated in the XML file used by MailIntegration.

      One or more errors occurred.

      AADSTS700016: Application with identifiers 'nac256aa-21b5-478e-b666-3840d367d596' was not found in the directory 'MonDomain.com'.
      This can happen if the application has not been installed by the administrator of the tenant or consented to by any user in the tenant. You may have sent your authentication request to the wrong tenant.

      Trace ID: 8361626f-1205-4ba4-car0-f887fdcc9c43

      Correlation ID: 1249af9c-83b8-422d-b34e-6dba83c0af35

      This indicates that the clientID parameter of your XML file is not valid.

      It is recommended to use the MailIntegration configuration tool to test this parameter.

      See the MailIntegration Configuration Tool article for more details.

      One or more errors occurred.

      AADSTS90002: Tenant 'octopus-itsm.com' not found. Check to make sure you have the correct tenant ID and are signing into the correct cloud. Check with your subscription administrator, this may happen if there are no active subscriptions for the tenant.

      Trace ID: 9f1298fe-1a2c-4ar9-b955-033941425a98

      Correlation ID: a6f8328f-be63-497b-8143-c0f6bfe3c40f

      This indicates that the tenantID parameter of your XML file is not valid.

      It is recommended to use the MailIntegration configuration tool to test this parameter.

      See the MailIntegration Configuration Tool article for more details.
      The timeout period elapsed prior to completion of the operation or the server is not responding.

      The POP 3 server is not allowed for this IP address or the network blocks the connection to the POP3 server.

      Validate that the port used by MailIntegration is open across all your network infrastructure and firewalls for the machine that is trying to access your mail server.
      The number of messages in the Inbox exceeds the maximum allowed (500).

      It is suggested that you manually check the mailbox read by mailintegration to identify the reason for the number of emails to be processed, such as out of office emails or notifications causing a loop.

      If everything seems ok, you must move the messages exceeding the number of 500 to a temporary folder and after processing by mailintegration, move them back in the inbox to finalize their processing.

 

2- .log File

If the information in the event is not clear enough or if an event has not been created, check the .LOG file to find the error message.

This file is normally created in the Octopus directory where MainIntegration is executed, or if not, in the path specified in the MailIntegration command line, parameter /LogFilePath.

By default, the fils is named MailIntegration_YYYYMMDD_HHMMSS.log and will be located in the Octopus directory.

More frequent error messages in the LOG file:

Messages Probable Causes

The Team parameter is invalid

This may indicate a lock of permission of the Octopus user specified in the MailIntegration command line of the team specified via the /Team parameter.

Note that this user must have a role with permission in each team where MailIntegration will be used.

ERR Logon failure: unknown user name or bad password.

This message indicates a password error in the mailbox.

This information is entered in the XML file declared in the MailIntegration command line (/ConfigFilePath parameter)

Network or POP3 server problems can also prevent MailIntegration form connecting to the mailbox. See the article Testing the POP3 connection article for more details.

Unknown Username or Incorrect Password

This indicates an error in the Octopus user'S password indicated in the command line  (/Password parameter)

Warning: email from xyz@octopus.com was not processed to avoid circular references

This email is ignored and not processed by MailIntegration in order to avoid creating looping incidents.

In the event created by this error, an .EML file with the copy of the ignored email is attached.

This indicates that an email with the same address of the box read by MailIntegration has been received.

 

3 - No message in the .log file

If there is no recent activity in the .LOG file, it is possible that MailIntegration is not able to be executed.

In this case, you must test the integrity of the Octopus client by running the file ESI.Octopus.WinUI.exe in the same directory as the MailIntegration program.

What you need to know:
  • It is important to pay attention to the .NET Framework prerequisites.
  • A version that is it not up to date can also prevent Octopus from working.

For more details, see the article Octopus System Requirements.

In this case, when running ESI.Octopus.WinUI.exe, the following message is displayed and the Octopus client does not start at all, the MailIntegration application mus be reinstalled, because the installation is corrupted.

 

Note:
Be careful not to lose the configuration files (XML, LOG and others) when reinstalling.
Ideally rename the directory to keep it and proceed with a new installation.

4 - Browser Cookies

 

Delete cookies and browsing history in the Windows profile that runs the MailIntegration task.

The Octopus application uses web components, so this is the reason why it is related to the cookies

5 - Others

You can contact Octopus Support if the client starts and there is no other information available.

Note: We recommend that you add the notification to the new events in order to be notified in case of problems. ( File -> My notification preferences (New Event)).

 

 

 

X
Help us improve our articles








Help us improve our articles