Microsoft Search Message

 

About

Microsoft Search Message search engine uses the Graph API to:

  • Send search queries to Microsoft 365
  • Search for information in email messages (body and attachments)
  • Receive emails from user's own mailbox

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 Message Search Engine to SmartHub

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

  1. Navigate to the SmartHub Administration page: http(s)://[web-app-url]/_admin
  2. Click Add New search engine. The search engine dialogue box appears.
  3. Type: Select Regular.
  4. Name: Enter a name for the search engine name.
  5. Search Engine: Select MS Search Emails from the drop-down list.


  6. Authentication: Select whether to enable or disable Impersonate authentication:
    1. Impersonate - true
      1. Security trims the results using the current user running the search
    2. Impersonate - false
      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: For example: https://login.microsoftonline.com
      4. Access Token: Enter the access token from SmartHub's OAuth page.

      5. Refresh Token: Enter the refresh token from SmartHub's OAuth page.

        Note: To get the Access token and Refresh token, the "Authorize" button must be clicked, but it needs all the above fields to be completed (GraphUrl, ClientId, ClientSecret, MicrosoftLoginEndpoint).
  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
    • Name: Enter the name of the application.
    • Application type: Select Web app / API.
    • Sign-on URL: Enter the SmartHub's URL.



  3. Select API Permissionsto open the settings menu panel.
  4. Click Add a Permission.
  5. Select APIs my organization uses and add the following permissions (as you type the name, it appears):
    1. Microsoft Graph
      • Mail.Read


  6. Click Certificates & secrets>New client secret to generate a client secret key.
  7. In the window that appears (shown below) 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

Metadata Info 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:

Example:

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

In this case, if you want to use property address, you need to add this property in SmartHub: sender.emailAddress.address

  • Microsoft called this properties "Recipient".

  • In case that the property from Microsoft Graph API returns a collection of "Recipient", in SH values for the specific property will be returned as string with ";" used as a delimiter.

  • The format for Recipient collection must be the same as above.

  • Recipient format is: propertyName.emailAddress.name / propertyName.emailAddress.address

  • Find all properties from Microsoft Graph here: https://docs.microsoft.com/en-us/graph/api/resources/message?view=graph-rest-1.0

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

Limitations

Note the following limitations when using the Microsoft Search Emails search engine:

  • Refiners are not supported.