Microsoft Search Items

This search engine was updated in SmartHub 5.6.6 to combine and replace the Microsoft Search External Items and the Microsoft Search Drive Items search engines. If you were using either of these search engines, you will need to remove them and add the Microsoft Search Items search engine after upgrading.

About

The Microsoft Search Items search engine uses the Graph API to query the following resource types (configurable at search engine level):

  • driveItem

  • list

  • listItem

  • site

  • externalItem

Limitations

The following are limitations for the Microsoft Search Items 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.

  • Date refiners are not supported by the Microsoft Search Items search engine.

  • Result sorting is not supported for External Items.

  • 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.

Application Permissions

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

  • Microsoft Graph
    • Files.Read.All or Sites.Read.All

How to Add the Microsoft Search Items search engine to SmartHub

Use the following instructions to add the Microsoft Search Items 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. search engine Name: Enter a search engine name.
  5. search engine type: Select the search engine type "MSSearchItemssearch engine".

    • driveItem

    • list

    • listItem

    • site

    • externalItem

  6. Connector Connection Id (only for externalItem): Enter the connection ID associated with your content.

    To get the Connection ID for your connector, do the following:

    1. Navigate to the Office Admin page.

    2. Click Settings > Microsoft Search.

    3. Click Connectors

      • A list of your current connectors appears with their connection IDs.

      • The connection ID value is the parameter that the search engine expects to receive.

  7. Graph Url:
    1. Example: https://graph.microsoft.com/
  8. 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: 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.

    In order to get the Access and Refresh tokens, the Authorize button must be clicked, but all of the above fields must 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.
  9. 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 window, 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
      • Files.Read.All
  7. Click Certificates & secrets > New client secret to generate a client secret key.
  8. 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 time period before the client secret expires from the drop-down list.
    3. A Value is generated after you click Add.

Metadata

The following metadata is available for your results:

  • rank
  • summary
  • @odata.type
  • lastModifiedDateTime
  • createdDateTime
  • webUrl
  • createdBy
  • name
  • size
  • lastModifiedBy

Note: For some types, not all metadata is available

Caution: When using the externalItem entity type in combination with the other native entity types (driveItem, list, listItem, site), you will need to handle discrepancies in the metadata scheme. ExternalItem items may use different names for the same metadata piece. For example, escbasetitle (in external items) vs name (in driveItem, list, listItem, site). Upland BA Insight recommends that you change the connector metadata schema to match the native entity types schema. By doing so, there will be no discrepancies when federating the different entity types at search time. This may require a full recrawl of your content source.

If normalizing the metadata schema is not possible, then do the following:

  • Use the Mapper for Query Text and Item Metadata setting to handle possible discrepancies for query text filters. For example, "test AND title:foo" might need to map to "test AND escbasetitle:foo". Use the same setting for item metadata that you need to display on the page. For example, title needs to map to both name and escbasetitle. For more information, see How to map metadata property values: Property Mapper.

  • If you want to show page refiners that have different names, you must have a separate refiner; one for the native entity types, and one for the external items. For example, to show the File Type refiner, you must have a File Type (for Drive items) that uses the filetype metadata and another File Type (for External items) that uses the escbasefileextension metadata. For more information, see Refiner Mapper Stage: Map Your Metadata Refiner Values.