Microsoft Search Emails

This search engine was updated in SmartHub 5.6.6 to replace the Microsoft Search Message search engine. If you were using this search engine in the previous version of SmartHub, you will need to remove it and add the Microsoft Search Emails search engine after upgrading.

About

The Microsoft Search Emails search engine uses the Graph API to search for information in Microsoft Outlook email massages.

Limitations

The following are limitations for the Microsoft Search Emails search engine. If a feature is not supported by the Microsoft Search Graph API, it will also be not supported by a Microsoft Search Graph search engine. For more information, refer to the Microsoft Graph API documentation.

  • Refiners are not supported by the Microsoft Search Emails search engine

  • The Microsoft Search Emails search engine can only return 10 items at a time.

  • If you are upgrading from an older version of SmartHub, the Microsoft Search search engines must be removed and re-added. For more information on upgrading, see How to Upgrade SmartHub.

Set Azure Active Directory Authentication

Set authentication to Azure Active Directory in SmartHub as described here: Azure Active Directory Authentication.

Client ID Requirements

The Client ID specified in Azure Active Directory Authentication above, must belong to an application with the following permissions, set in Azure:

  • Microsoft Graph
    • Mail.Read

How to Add the Microsoft Search Emails search engine to SmartHub

Use the following instructions to add the Microsoft Search Emails search engine to SmartHub:

  1. Navigate to the SmartHub Administration page: http(s)://[web-app-url]/_admin
  2. Click Add New search engine.
  3. The search engine Settings dialogue box appears.
  4. Enter a search engine name.
  5. Select the search engine type "MSSearchEmailssearch engine"
  6. Authentication
    1. If you set Impersonate to true, security trims the results using the current user running the search
    2. If you set Impersonate to false, complete the following fields and click Authorize: 
      1. Client Id:
        • Enter the Application ID from Azure App Registrations.
      2. Client Secret:
        • Enter the Key's value from Azure App Registrations.
      3. Microsoft Login Endpoint:
      4. Access Token:
        • Enter the access token from SmartHub's OAuth page.

      5. Refresh Token:

        • Enter the refresh token from SmartHub's OAuth page.

        In order to get AccessToken and Refresh token, "Authorize" button must be clicked, but it needs all above fields to be completed (GraphUrl, ClientId, ClientSecret, MicrosoftLoginEndpoint).
        If you do not wish to use Impersonate, you must move the Redirect URI to the Web section instead of the Single-page application section in your SmartHub Azure app registration. For more information, see this question and answer in the Microsoft documentation.
  7. Click OK.

How to Register an App in Azure and Configure It

If you use SmartHub with Azure Active Directory authentication you can reuse the same App and jump to step 5.

  1. Navigate to portal.azure.com and log in.
  2. From the left side menu go to Azure Active Directory > App registrations > New registration.
  3. On the Register an application page, specify the following:
    • Name: Enter the name of the application.
    • Application type: Select Web app / API.
    • Sign-on URL: Enter the SmartHub's URL.
  4. Select API Permissions to open the settings menu panel.
  5. Click Add a Permission.
  6. Select APIs my organization uses and add the following permissions (as you type the name, it appears):
    1. Microsoft Graph
      1. Mail.Read
  7. Click Certificates & secrets > New client secret to generate a client secret key.
  8. In the Add a client secret window, enter the following information.
    1. Description: Enter a name for the client secret. (Note: The name is your client secret).
    2. Expires: Select the period until expires.
    3. A Value is generated after you click Add.

Metadata

In order to use the properties received from Microsoft Graph, properties are flattened. BA Insight does this because Microsoft Graph API returns properties in this format:

"sender":{"emailAddress":{"name":"ExampleName","address":"no-reply@examplename.com"}}}}

In this case, if you want to use the address property, you need to add this property in SmartHub: sender.emailAddress.address. Microsoft calls this type of property "recipient" as it contains information about the user sending the email. If the property from the Microsoft Graph API returns a collection of recipient's, the values for the specific property in SmartHub will be returned as string with ";" used as a delimiter.

The format for Recipient collection must be the same as above: propertyName.emailAddress.name / propertyName.emailAddress.address. For more information on all the properties for the message resource type from Microsoft Graph, see message resource type in the Microsoft documentation

The following metadata is available for your results:

  • @data.type
  • summary
  • rank
  • bccRecipients.emailAddress.address
  • bccRecipients.emailAddress.name
  • body.content
  • body.contentType
  • bodyPreview
  • categories
  • ccRecipients.emailAddress.address
  • ccRecipients.emailAddress.name
  • changeKey
  • conversationId
  • conversationIndex
  • createdDateTime
  • flag
  • from.emailAddress.address
  • from.emailAddress.name
  • hasAttachments
  • id
  • importance
  • inferenceClassification
  • internetMessageId
  • isDeliveryReceiptRequested
  • isDraft
  • isRead
  • isReadReceiptRequested
  • lastModifiedDateTime
  • parentFolderId
  • receivedDateTime
  • replyTo.emailAddress.address
  • replyTo.emailAddress.name
  • sender.emailAddress.address
  • sender.emailAddress.name
  • sentDateTime
  • subject
  • toRecipients.emailAddress.address
  • toRecipients.emailAddress.name
  • webLink