The EzeScan Microsoft Office Outlook 365 connector from Outback Imaging provides users with a native Microsoft Graph API based method for connecting to Microsoft Office 365 email systems for the processing of Emails in EzeScan.

Developed for Ezescan Release: 5.0.24

NOTE

This information below and EzeScan PRO manual excerpt assumes knowledge in both EzeScan and in typical I.T. practices and terminology.

The Connector itself has been designed to provide the same overall functionality as per the standard IMAP connector, with a few differences noted (due to differences in the Microsoft Graph API functionality).

• Authentication via Microsoft’s Modern OAuth authentication methodology.
• Email Folders display as a Folder Name/GUID in configuration.
• Additional option of “Mark Email as Read after Move” (default ticked).
• Additional option of “Download Newest Emails First” (default unticked).
• The Microsoft Graph API returns an approx. 152 character GUID for <<Email:Uid>>.

NOTE

This document describes the functionality and authentication methodology for connecting EzeScan to an email protocol for the purposes of downloading and processing email and includes all current supported email protocols of O365, IMAP and POP3.

Licensing of O365

As the connector (at the time of writing) is a relatively new addition to EzeScan, the majority of EzeScan Customers with Email Capture licensing will not have the EzeScan Microsoft Office Outlook 365 connector enabled in their licensing.
In order to enable the use of the connector a customer will need to contact EzeScan to have their licensing reissued to include the O365 Connector.

NOTE

There is no charge for the Connector’s licensing inclusion for Organisations who are up to date with their software support and maintenance.

For those Organisations who are out of maintenance, please contact your local EzeScan reseller or Outback Imaging (EzeScan) for options.

Supported Releases of EzeScan

In order to utilise the EzeScan Microsoft Office Outlook 365 connector an organisation will need to update their EzeScan instances to the recommended EzeScan version of 4.3.194 or higher. 

TIP: As EzeScan evolves so too will the O365 connector and from time to time an Organisation should review the current EzeScan release notes for any changes that may be relevant to themselves.

Release Notes Link (login required):
https://ezescan.com.au/support/ezescan-43-features-and-fixes

Referencing the O365 Connector

The EzeScan Microsoft Office Outlook 365 connector is referenced from an EzeScan Job or an EzeScan Server Route.

When migrating an organisation’s settings over to the O365 connector the most ideal method is to create the O365 connector as a new Import Source for the target job or server route and when completed the changeover would be to untick the original IMAP/POP3 Import Source and tick the Office 365 Connector Import Source.Here a number of different email based imports sources are configured where swapping 
between is a simple matter of ticking and unticking the required checkboxes.


An Organisation may also want to familiarise themselves with the connector’s operation prior to migration of settings and to do so a new EzeScan Job can be created and configured for exclusive use of the EzeScan Microsoft Office Outlook 365 connector as its Folder Import Source.

Microsoft Modern OAuth Authentication

Below is a short description of Microsoft’s implementation for their Modern Authentication taken from their Exchange online webpages.

“Modern authentication in Exchange Online enables authentication features like multi-factor authentication (MFA) using smart cards, certificate-based authentication (CBA), and third-party SAML identity providers. Modern authentication is based on the Active Directory Authentication Library (ADAL) and OAuth 2.0.”

https://docs.microsoft.com/en-us/exchange/clients-and-mobile-in-exchange-online/enable-or-disable-modern-authentication-in-exchange-online

In order to use the OAuth authentication protocol EzeScan requires a trust relationship and tokens issued from the Office 365 authentication management websites.

EzeScan supports two authentication configuration options being,

  • Custom (Internal customer app registration)
  • InBuilt App (registration provided by EzeScan)

Custom is where an Organisation will define their own trust relationship with Microsoft O365 for use with EzeScan. This process would be performed in the azure portal in app registrations.

InBuilt is a pre-configured trust relationship that should function for the majority of use configurations and is the simplest to configure within EzeScan.

The KFI Field Settings allow the operator to browse M-Files data during KFI indexing so the operator can select a value and other object types to be applied to the document.

App Registration


The below Microsoft links provide more information:

https://docs.microsoft.com/en-us/graph/auth-register-app-v2

https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-configure-app-access-web-apis

https://docs.microsoft.com/en-us/graph/auth-limit-mailbox-access

The administrator would choose the account type (this needs to be noted for EzeScan configuration later)

The redirect URI needs to be configured. We recommend http://localhost (this needs to be noted for EzeScan configuration later)

The client secret needs to be created this needs to be noted for EzeScan configuration later.

NOTE

When creating the secret, we require the secret value, not the secret ID. This needs to be copied upon creation as it can’t be retrieved again. If in error, delete and create a new secret.

The API permissions to be configured.

Select Microsoft Graph

If using an Admin Consent:

Select Application permissions and choose:

  • ReadWrite
  • Read.All

Configured permissions

NOTE

The the default of User.Read is not required and can be removed.

If using an OAuth token:

Select Delegated permissions and choose:

  • readwrite
  • readwrite
  • read
  • offline_access

Configured permissions

Once all this is completed the EzeScan configuration can be performed.

The following information needs to be noted:

  • Registration Type (Single-Tenant ID or Multi-Tenant ID)
  • Client ID
  • Client Secret
  • Redirect URI

Please refer to your local Microsoft Azure administrator for further information regarding custom application configuration within Microsoft Azure.

Migration of settings from IMAP to O365

Migration will consist of duplicating the previously used email settings into the new O365 Connector settings, noting there will be some differences and potential changes due to different Graph API functionality.

An organisation will need to make a decision on any further changes (outside of plain duplication of settings) that maybe required due to the Graph API differences.

There will also be the authentication configuration (InBuilt or Custom) requirements as defined to the organisation’s requirements.

Please contact support at any time by emailing support@ezescan.com.au or by telephone during business hours to our call handling service on 1300 EZESCAN (from outside Australia, +61 1300 393 722 or +61 7 3051 5890).

Further contact information can be found here.

Import Source Email Configuration

The following pages are an excerpt from the EzeScan PRO user guide and covers Email configuration options for IMAP/POP3 and O365.

Functionality is added as Import Folder “Import Sources” as shown at right and is applicable to both an EzeScan Client and EzeScan Server configurations.

IMAP/POP3/MICROSOFT OFFICE 365 Configuration


IMAP, Microsoft Office 365 and Pop3 use the similar types of settings (see below)

When selected the Connector option tells EzeScan to retrieve images from a nominated email mailbox via the selected protocol.

Available protocols are POP3, IMAP or Microsoft Office 365 where EzeScan will poll the nominated email mailbox and import emails and attachments for processing.

In this configuration we describe IMAP, however the POP3, IMAP and Microsoft Office 365 email connection and configuration settings are all very similar.

IMAP, Microsoft Office 365 and POP3 also all use different ports, additionally IMAP and Microsoft Office 365 have the ability to choose email folders to import email from, as well as being able to move the email into alternate folders once the email has been imported. POP3 has only the ability to import emails as a whole.

Please refer to your email server administrator for the details of the email protocol EzeScan would need to use.

TIP: IMAP and Microsoft Office 365 are the preferred email protocols as they provides options POP3 is incapable of provisioning.

Connection Settings (IMAP/POP3)


Server, Port, Username and Password

Use these fields to configure the default settings for the mailbox from where you want to download emails.

Enter the appropriate values for the Server Name (or its IP address), Port, Username and Password, as well as the Security Type.Example of server, port username and password set-up


Ports are related to the type of IMAP connection, for example.

  • Port 143 is for the Security Types of NONE and EXPLICIT
  • Port 993 is for the Security Type of IMPLICIT

Please refer to your email server administrator for the details of the type of Security in use for your Organisation’s email server, they will typically also be able to provide such details as the server name, username and password.

Import Document Settings


The Import Document Settings is the area related to the configuration the currently selected connector will use when downloading emails.

Values entered here will configure the methods of processing for downloading emails from an email server.

The pic below displays the settings particular to the IMAP protocol noting the Import Document Settings dialog will display only the settings as provided by the protocol in use.IMAP download configuration options

DESCRIPTIONS:

Mailbox

This option allows the user to specify the IMAP mailbox from which to download emails, the default is set to Inbox.

Subfolders maybe selected and are shown in the list separated by a forward slash
eg INBOX/AP Accounts for processing

Filter Expression

This option will allow to include or exclude emails from a specific domain and filter by attachments. E.g.
{from} contains {ezescan.com} will only include emails from ezescan.com
{from} not contains {ezescan.com} will exclude emails from ezescan.com
{from} contains {ezescan.com.au} and {from} contains {ezescancloud.com} will include emails from ezescan.com and ezescancloud.com
{attachment} not contains {ATP Scan In Progress} will exclude emails that are being scanned by office 365 threat detection.

Prompt for subfolder

Enable this setting for if there are subfolders under the mailbox to be processed. This will allow the operator to see the subfolder under the specified mailbox and choose one to import emails from.

Move to Mailbox:

Specify the IMAP mailbox to move the email to after processing, or leave blank to delete the email.

It is recommended to create a mailbox folder named Processed and then select it in this section. EzeScan will then move all processed emails to this mailbox from the selected inbox.

For testing purposes the Move To Mailbox value can be set as the same as the Mailbox import folder. The result will be the email remaining in the source mailbox folder.

NOTE

The mailboxes must be a proper mailboxes i.e. have a legitimate email account & cannot be a public folder or shared access type of email account.

Select emails to download

This will display a list of emails that reside in the mailbox and the operator can select which email to import.

Download attachments filter

Set this to either look for emails that have attachments configured in the import file types setting or sell to all for all attachment file types.

Filter emails by attachments

Enable this setting to only process emails with attachments.

Download Count Limit

Specify the number of emails to display/download, default is zero (0) for unlimited. If a number is set it will show the X number of oldest in that mailbox.

Document Basename

This allows the basename of the emails and attachments to be customised.

Where no Basename has been specified the default naming schema used is, Email_<<S3(YYYYMMDD)>>_<<S4(HHMMSS)>>

Available document basename placeholder options are:

<<Email:ToAddress>>

<<Email:ToName>>

<<Email:FromAddress>>

<<Email:FromAddress>>

<<Email:Subject>>

<<Email:Uid>>

<<Attachment:Base>>

<<Attachment:Ext>>

<<Attachment:Index>>

<<Attachment:Number>>

<<Attachment:Count>>

<<S3>> (Date)

<<S4>> (Time)

Create index from headers

This option will create an XML index file (in the specified import folder of the job) which will contain header information of the email.

These include:

  • From, To, CC, BCC, Reply Address, UID
  • Subject, Body
  • Date, Date Downloaded

The operator can use the optional licensed KFI module to extract this data for KFI field processing. Please refer to the “Entry in data file” feature in the Value Tab in the KFI User Guide.

  • Convert HTML body to XML

Convert HTML email body to XML when inserting into the XML index file

  • HTML tags to remove

Enter the name of the HTML tags to remove when converting the HTML body to XML

For example: “img;br;script” where each tag separated by a semi-colon.

Generate .eml file from email

When ticked this option tells EzeScan to download each individual email as an .eml file.

This will allow EzeScan to process both the body of the email as well as any attachment (rather than simply all attachments).

EzeScan uses the Email Render Profile to convert imported .eml files to tiff for processing.
See Render Profiles > Email Settings for more information.

File system subfolder

This setting works in conjunction with the “prompt for subfolder” settings.

If a subfolder is being used EzeScan can drop the documents into a subfolder (under the import folder) of the same name.

The placeholders available are.

<<Mailbox>> - i.e. INBOX

<<MailboxPath>> - i.e. INBOX/Customers/ABC Pty Ltd

<<MailboxRelativePath>> - i.e. Customers/ABC Pty Ltd

Mark Email as Read after Move

O365 Only

Optionally mark the email as read after moving the email to the designated target email folder. (Default ticked)

Download Newest Emails First

O365 Only

Swap between downloading the Oldest or newest emails in the designated mailbox.

(default unticked)

Connection Settings (O365 Outlook)


The EzeScan Microsoft Office365 Outlook Connector is built to connect to Microsoft’s Office365 product and is based upon the Microsoft Graph API using OAuth as the authentication method.

NOTE

Web based applications such as Microsoft Office 365 typically require specific configuration for OAuth, where the application requiring access will be configured within the Web application and include parameters for authorisation.

For the EzeScan Microsoft Office365 Outlook connector there are four options applicable to the connection method:

When configuring the new connection, it is advised to run EzeScan as an Administrator as most operating systems require local admin access to bind to a network interface and listen for OAuth Redirect callbacks (e.g. http://localhost).

Inbuilt Authentication

The Inbuilt option is a simplified configuration suitable for the majority of Organisations where the OAuth application authorisation has been pre-built leaving just the need for the Office 365 Sign-In.

The Custom option allows an organisation to configure their own specific OAuth application authorisation.

The Tenant, Client ID, Client Secret and Redirect URI are part of the App Registration process. This makes Microsoft's services aware of the EzeScan Connector and provides the Connector with the authorisation details necessary to perform OAuth authorisation.

Sign-in to Microsoft Office 365

Enter the appropriate Microsoft Office 365 account details. 

Enter the matching password. 

Choose to Stay signed in or not - Yes would be typical.

Upon first registration the connector may require approval.The Azure Administrator will be required to approve the connector.

If using Admin Consent

Once the wizard above has been completed this screen may return an error

This page isn’t working

localhost didn’t send any data.

ERR_EMPTY_RESPONSE

Close the tab and the connection has been completed. The operator can then configure the Mailbox and Move to Mailbox Settings.

If using an OAuth sign-in

Once signed in an Access Token will be generated and populated into the OAuth Sign-In field.

Tokens do expire where the actual expiry length is defined by the Microsoft Authentication services.

In the token itself the authentication expiry time length of the token is defined by the token value of "additional_properties":{"ext_expires_in":"3599"}} where 3599 demonstrates the value in seconds, e.g. 3599 seconds is one hour minus one second.

The operator can then configure the Mailbox and Move to Mailbox Settings.

NOTE

Although a token does expire, it will auto refresh upon expiry (both in EzeScan the Client and in EzeScan Server).

Microsoft Office Outlook Connector Differences


Most of the Import Document Settings are the same or similar to those of IMAP with differences noted below.O365 Connector download configuration options highlighting differences between IMAP

The Mailbox Browser and Select Emails windows have a different look
Mailbox and Move to Mailbox folder selection and display

When the Mailbox field is populated the name of the folder and a GUID is used to identify the target folder.

Document Basename

If the configuration specifies a custom document base name and one of the base name elements is…

  • <<Email:Uid>>

Be aware the Uid returned by the Graph API is a GUID of 152 characters in length that may likely have an impact on Windows path and EzeScan field length allowances and its use should be reviewed in light of the Uid being such a long string of characters.

If no Basename is defined emails will be downloaded using the following naming schema.

  • Email_<<S3(YYYYMMDD)>>_<<S4(HHMMSS)>>
The Microsoft Office 365 Connector also includes the following additional items

Mark Email as Read after Move                  (default ticked)

Download Newest Emails First                    (default unticked)

Where emails can optionally be not marked as read when moved and emails can be downloaded based on newest first or if unticked the oldest emails are downloaded first.

EzeScan Shortcut Keys

Please refer to the How to articles.