Microsoft Office 365 Outlook
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.72
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 5.0.72 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.
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 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.”
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.
This integration only supports OAuth 2.0 authentication as required by the Graph API it uses to connect with Microsoft 365.
The supported grant types are as follows:
Client Credentials (recommended for background service)
Authorization Code (recommended for desktop usage)
The following grant types are not supported due to the security risks they pose:
Resource Owner Password Credentials - https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-oauth-ropc
Connection Settings
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.
Option | Description |
|---|---|
OAuth Registration | Use this OAuth registration for authentication with Microsoft identity platform. Default option is Inbuilt. Custom allows the use of your own app registration and is recommended when finer grain control is required. |
Tenant ID | The GUID or friendly name of the directory tenant to request permissions from. Leaving this blank will allow sign-in from any directory tenant. |
Grant Type | The OAuth grant type to use, default is Authorization Code. The available options are:
Authorization Code is recommended for EzeScan Desktop usage, and will require the user to sign-in via the web browser. Client Credentials is recommended for EzeScan Server usage as it does not require user interaction to complete a sign-in. |
Allow Shared Mailbox | Request additional permissions to download emails from a shared mailbox or another user's mailbox. |
Admin Consent | Use this to open a web page for an administrator in your Azure AD directory to grant the connector consent to use the respective permissions on behalf of users. This only needs to be completed once. |
The following settings are only applicable when using a Custom OAuth registration.
Option | Description |
|---|---|
Client ID | The Application ID of the app registration in Azure. |
Client Secret | The Secret Value that was generated on the app registration in Azure. Do NOT use the Secret ID - this will not work. Please note that a new secret will need to be generated and applied in EzeScan before the expiry date elapses otherwise the connector will no longer connect to Outlook. |
Desktop Redirect URL | Redirect URI that will be navigated to on completion of sign-in process. Default is http://localhost. The redirect URL used for EzeScan Server is it's hosting address with the suffix |
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).
Import Source Email Configuration
Functionality is added as Import Folder “Import Sources” as shown at right and is applicable to both an EzeScan Client and EzeScan Server configurations.
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.
Option | Description |
|---|---|
Mailbox | The user id or user principal name (e.g. invoices@ezescan.local) of the mailbox to download emails from. This option can be left blank when using OAuth Authorization Code flow to use the authenticated user's mailbox. To access another users mailbox the that user must be licensed in Azure, and the authenticated user must be granted permissions to access their mailbox. Refer to the below link for granting a user access to another mailbox. |
Source Folder | This option allows the user to select the mailbox folder from which to download emails, the default is set to Inbox. |
Filter Expression | This option will allow to include or exclude emails from a specific domain and filter by attachments. E.g. |
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 folder | Specify the mailbox folder 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 Folder value can be set as the same as the Mailbox import folder. The result will be the email remaining in the source mailbox folder. |
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. |
Email search filter | Optionally restrict email search using one of the following filters:
|
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, Available document basename placeholder options are:
|
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:
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. |
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.
|
Mark Email as Read after Move | Optionally mark the email as read after moving the email to the designated target email folder. (Default ticked) |
Download Newest Emails First | Swap between downloading the Oldest or newest emails in the designated mailbox. (default unticked) |