Exchange (CMIS Binding)

From Grooper Wiki

This article is about the current version of Grooper.

Note that some content may still need to be updated.

2025 20232.72

Exchange is a connection option for cloud CMIS Connections. It connects Grooper to Microsoft Exchange email servers (including Outlook servers) for import and export operations.

The Exchange Connection Type allows you to access Outlook files and folders. You can access mail messages, calendar appointments, contact cards, and tasks all using this binding. Once connected, you can import full mail message threads and attached files into Grooper.

About

Microsoft Exchange Server is "a mail server and calendaring server developed by Microsoft".

  • Microsoft Outlook is an email client that is usually hosted on Exchange servers.
    • If using Outlook with a Microsoft 365 subscription, your email is (typically) hosted on Exchange Online (outlook.office365.com).
    • In corporate environments, Outlook often connects to an on-premise Exchange server managed by the organizations IT.

The "Exchange" CMIS Binding provides Grooper connectivity to Microsoft Exchange mail servers (on-prem Exchange or Exchange Online) via Exchange Web Services. This enables Grooper to access, search and manage mail messages, appointments, contacts and tasks from one or more Exchange mailboxes. Mailboxes are exposed to Grooper as a CMIS Repository. CMIS Repository nodes are created as children of the CMIS Connection by importing a reference to their source location.

The Exchange CMIS Repository allows Grooper to "see" emails in the mailbox. Once a CMIS Repository is created, you can import, browse and query emails from Grooper.

  • The Exchange binding can be used for import operations via CMIS Import using "Import Descendants" or "Import Query Results".
  • It can be used for export operations via CMIS Export.
    • While it's common to import documents from an email source, it's not common to export documents to an email source. While exporting to a CMIS Repository using the Exchange binding is technically possible, it is not common. While exporting to an Exchange CMIS Repository is partially documented in this article, it is not widely done in production scenarios.

How To: Create a New Exchange Connection

  1. Expand your Projects Folder.
  2. Right-click the Project.
  3. Select "Add", then "CMIS Connection".
  4. Name your CMIS Connection.
  5. Then click "Execute."
  6. On the CMIS Connection tab, select "Exchange" from the "Connection Settings" drop-down menu.
  7. Enter the host name or IP address of the Microsoft exchange server.
    • outlook.office365.com is the hostname for Exchange Online.
  8. Choose your Authentication Method.
    • Auto Authentication - Authenticates automatically using the current Windows user's credentials.
    • Basic Authentication - Implements Basic HTTP Authentication as defined in RFC-7617. If you choose this option, you will need to enter your user name and password
    • NTLM Authentication - Implements NTLM Authentication as defined in MS-NLMP. If you choose this method, you will need to enter the Windows Active Directory domain name and user name and password.
    • OAuth Authentication - Implements OAuth 2.0 for connections to Exchange. If you choose this method, you will click a nested button to log in using a Microsoft account.
  9. Under "Mailbox Llist", press the ellipses button to bring up a List Editor.
  10. Here you can enter a list of email addresses you want to access as repositories.
    • This means you can access multiple emails using one "super-user" account.
  11. Select "Import Repository" to bring in these repositories for Grooper to import and export to the corresponding folders in the connecting file system.
  12. This False icon will turn to True once the repositories have been imported.
  13. Selecting the imported repository, you see you can have access to all email folders from messages to contacts.
  14. You can bring in any email message, including attached files into Grooper.

Importing and Exporting using an Exchange CMIS Connection

Importing

Submitting an Import Job with Exchange from the Batches Page

  1. Click the Imports icon.
    • IMPORTANT: You will need to have an Import Watcher service installed and running prior to submitting an Import Job.
  2. Click the Add New Jobs button.
  3. Enter a description for your Import Job.
  4. Choose Import Query Results for your Provider.
    • Exchange enables a user to import across an entire mail server. While powerful, having to sort through each imported message can be a tedious hassle. Import Query Results is a good option for narrowing down results based on certain conditions and search criteria such as a sender's name or key words within the message or subject line.
  5. Select the Exchange Repository you will be importing your Batch from.
  6. Configure your CMIS Query.
  7. When finished, click Submit.
  8. Once your Import Job is complete, go to the Design page, then Batches --> Test --> Imported Batches and select the newly imported Batch to view the contents.

Exporting

  • While it's common to import documents from an email source, it's not common to export documents to an email source. While exporting to a CMIS Repository using the Exchange binding is technically possible, it is not common. While exporting to an Exchange CMIS Repository is partially documented in this article, it is not widely done in production scenarios.

Configuring an Export Behavior

Click here for an interactive walkthrough

  1. Click ... at the end of the Behaviors property to begin configuring.
  2. Within the Behaviors List window that appears, click the add button and select Export Behavior.
  3. Click ... at the end of the Export Definitions property.
  4. Click the add button within the Export Definitions List Window and select CMIS Export.
  5. To choose the Repository, click the hamburger icon at the far end of the CMIS Repository property, and click through the dropdown menu.
  6. Select the Exchange Repository.
  7. Click ... at the end of the Target Folder property to choose a specific folder or sub-folder if you do not wish to export your Batch to the root folder of the Repository.
  8. Define the Object Type.
  9. Click OK when finished configuring the Export Definition.
  10. Click OK to finalize the Export Behavior.
  11. Save.

Exchange CMISQL Query Examples

You can search across all item types, including searching for e-mail messages. A use for this could be using Import Query Results to narrow down what you want to import across one or more mailboxes based on sender and/or words in the subject line.

Query 1

SELECT * FROM Message WHERE HasAttachments=True AND Subject LIKE '%Sales Order%' AND Subject LIKE '%grooper%' AND DateTime Received>='1/1/2018'


This query would search the Message content type for certain property values. Namely, that the messages have attachment, contain the words "Sales Order" and "grooper" in the title and were received after Jan 01, 2018.

Note you cannot search for "identity" in a subject line.

  • You cannot use the = operator to search for something in a subject.
  • Instead, use the LIKE operator. Search using grammar like this: Subject LIKE '%put what you're searching for here%'

Query 2

SELECT * FROM Item WHERE CONTAINS ('grooper AND 2023 AND beta')

You can also search across all content types. This query would return any Messages, Contacts, Appointments or Tasks that have the words "grooper" "2023" and "beta" in their text (including subject lines). You also have access to OR and NOT operators.

Exchange CMIS Content Types

The Exchange Binding has five "CMIS content types": Item, Messages, Appointments, Contacts and Tasks. Each one has its own set of properties you can query using CMISQL queries (Either using a CMIS Repository's "Search Tab" or using Import Query Results to import files from an inbox). The "Item" content type is a base type from which all four content types inherit. It defines a common set of properties to the other four content types. All five content types are full text searchable using the CONTAINS() predicate.

Content Type Description Properties
Item The base type item, which all content types inherit.

Users should only query using this content type if they want to return files of all types (Messages, Appointments, Contacts and Tasks).

  • Subject
  • Size
  • Has Attachments
Message Represents an email message.

This is the most commonly used Exchange content type. Most typically users want to query/import email messages.

  • MIME Type: message/rfc822
  • File Extension: .eml
  • Subject
  • Sender
  • To Recipients
  • Cc Recipients
  • Bcc Recipients
  • Date Time Recieved
  • Date Time Sent
  • Is Read
  • Size
  • Has Attachments
Appointment Represents a calendar appointment
  • MIME Type: text/calendar
  • File Extension: .ics
  • Subject
  • Organizer
  • Size
  • Has Attachments
Contact Represents a contact card.
  • MIME Type: text/x-vcard
  • File Extension: .vcf
  • Display Name
  • Subject
  • Size
  • Has Attachments
Task Represents a task
  • MIME Type: text/plain
  • File Extension: .txt
  • Subject
  • Size
  • Has Attachments

OAuth Service Login setup

OAuth Service Login is the preferred Authentication Method for Exchange connections. The OAuth Service Login method implements OAuth 2.0 authentication using the client credentials flow for secure server-to-server access in Grooper. This method is preferred because:

  • It is a secure standard for connecting applications over web calls.
  • Compared to OAuth user login and other authentication methods, it reduces the number of times a connection has to be re-authenticated.
  • You can set longer expiration dates for client secrets than an organization's IT typically sets for user password.
  • OAuth Service Login was developed for use with Microsoft Entra ID authorization servers. Other authorization servers may work but have not been verified, will not be supported and will not be documented in this article.

How OAuth works:

  1. App Registration: The application registers with the authorization server and receives a "client ID" and "client secret". This is like the username and password for the application. Part of the OAuth Service Login setup will be registering Grooper with Microsoft Entra ID.
  2. Token Request: The app sends a request to the token endpoint with its credentials. The token endpoint for Entra ID is https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token.
  3. Token Response: The server validates the credentials and returns an access token. The Grooper's client ID and client secret in the app registration are the credentials the server validates.
  4. API Access: The app uses the token to make authorized API calls. This is what allows Grooper to make calls to the Exchange Web Services (EWS) API.

Step 1: Register Grooper with Microsoft Entra ID (formerly Azure AD)

Your first step is making an app registration for Grooper in Microsoft Entra ID (formerly Azure Active Directory). This registration will identify Grooper as a trusted application within your tenant and allow Grooper to securely interact with Exchange Web Services.

Create the app registration

  1. Go to the Microsoft Azure portal (portal.azure.com)
  2. Search for "Microsoft Entra ID"
  3. Under "Manage", select "App registrations".
  4. Press the "New registration" button.
  5. Enter a name for the app registration.
  6. Select the "supported account type".
  7. Press the "Register" button to register the app.

Make note of the "client ID" and "tenant ID" (You will need these later).

In the app registrations "Overview" screen, make note of the "Application (client) ID" and "Directory (tenant) ID" values.

  • Application (client) ID = Client ID
  • Directory (tenant) ID = Tenant ID

Create a client secret and copy it down (You will need this later).

  1. In the "Overview" screen, click the "Add a certificate or secret" link next to "Client credentials".
  2. Press the "New client secret" button.
  3. Name the client secret (Description) and set an expiration date (Expiration).
  4. Press the "Add" button.
  5. Under "Value" copy the client secret using the "Copy to clipboard" button.
    • This is your only chance to copy the client secret. Do not lose it. You will need it later when configuring the Grooper web server.

Configure API permissions.

You will need to add a few Microsoft Graph permissions to allow the app (Grooper) to query mailboxes and retrieve messages.

  1. Under "Manage", go to the "API permissions" screen.
  2. Select "Add a permission".
  3. Select "Microsoft Graph".
  4. Select "Application permissions".
  5. Search for and select the following permissions:
    • User.Read
  6. Go back to "All APIs".
  7. Select "APIs my organization uses".
  8. Search for "Office 365 Exchange Online".
  9. Select "Delegated permissions".
  10. Search for and select the following permissions:
    • Mail.ReadWrite
  11. Select "Application permissions".
  12. Search for and select the following permissions:
    • full_access_as_app
  13. Select "Add permissions" to add the selected permissions.
    • If at any point in this process the "Add permissions" button is disabled after clicking on a permission, you may need to add each of these permissions "one-by-one".
    • Admin consent may be required for these permissions. If you are not your organization's Azure administrator, you will need to request these permissions are approved by your administrator.

Step 2: Configure the CMIS Connection

When configuring the CMIS Connection you will need the following information from Azure:

  • Your organization's tenant ID ("Directory (tenant) ID").
  • The app registration's client ID ("Application (client) ID").
  • The app registration's client secret value.
  1. Select the CMIS Connection in your Project (or add one if you have not done so already)
  2. (If not done already) Set the "Connection Settings" property to "Exchange" using the dropdown list (menu).
  3. Expand the Connection Settings properties (Press the ⮞ button).
  4. (If not done already) Enter the host name or IP address of the Microsoft Exchange server.
    • outlook.office365.com is the hostname for Exchange Online.
  5. Set the "Authentication Method" to "OAuth Service Login" using the dropdown list (menu).
  6. Expand the Authentication Method properties (Press the ⮞ button) and configure them.
    • For "URL", enter the following token endpoint for Entra ID:
      • https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token
      • Replace {tenantId} with your organization's tenant ID from Azure.
    • For "Client ID", enter the client ID for the app registration from Azure.
    • For "Client Secret", enter the client secret for the app registration from Azure.
    • For "Scope", enter the following:
      • https://outlook.office365.com/.default
  7. (If not done already) Open the "Mailbox List" editor (Press the "..." button) and enter the mailbox(es) you want to connect to.
    • You must enter at least one mailbox.
  8. Save your changes.
  9. Import the desired mailboxes as CMIS Repositories.

Known Issues & Limitations

Exchange CMISQL Query Limitations

When configuring a WHERE clause (using a Comparison Predicate), the "Subject", "Sender", "To Recipients", "Cc Recipients", and "Bcc Recipients" cannot use the = operator.

  • Use the LIKE operator instead.
    • Incorrect syntax: Sender = '%user@example.com%'
    • Correct syntax: Sender LIKE '%user@example.com%'
  • BE AWARE: EWS only supports substring matching for these properties. You must use the % wildcard on either side of the search term when using the LIKE operator.
    • Incorrect syntax: Sender LIKE 'user@example.com'
    • Correct syntax: Sender LIKE '%user@example.com%'
Retrieved from "https://wiki.grooper.com/index.php?title=Exchange_(CMIS_Binding)&oldid=31065"