Connect SmartHub to your search engine

Procedure:

1. Go to your Azure Cognitive Search Service.
2. Click Overview > Indexes.
3. Select your index that will be used also in SmartHub.
4. Select Scoring Profiles > Add scoring profile.
5. Enter a scoring profile name and click Add scoring profile.
   
6. Click Add functions > Add Scoring function.
7. From the Function type dropdown, select Freshness.
8. Choose Field name for boosting.
9. Choose interpolation:
   • Required for scoring functions.
   • Defines the slope for which the score boosting increases from the start of the range to the end of the range.
10. Choose a Boost value:
    •  Required for scoring functions.
    • A positive number used as multiplier for raw score. It cannot be equal to 1.
11. Choose Boosting duration (Sets an expiration period after which boosting stops for a particular document.)
    1. The Boosting duration must be formatted as an XSD "dayTimeDuration" value.
    2. Example: "P1D" (1 day), "PT15M" (15 minutes)
12. Click Ok > Save.

Vector Search

You can learn more about vector search by referring to Enhancing search results with Vector Search. For more details about the search performed in Azure, see Deciding which type of search to use. By default, pure vector search is enabled if the Azure Translator Stage exists.

Enable Vector Queries

In order for SmartHub to perform vector queries, the VectorQueries property of the SearchQuery object must be populated. This can be achieved through a Query Tuning Stage. A sample script for generating vector queries using OpenAI can be found at Generate vector is a Query scripting pipeline.

Retrieve And Process Vector Field(s)

Although it is not recommended to return vector field(s) on the returned results, there may be cases when it is needed. To achieve this, do the following:

1. Navigate to your results page.

2. Edit this page using the UI Editor.

3. Select the Basic mode

4. Open the Customize ContentContainers section.

5. On the left side panel, select and edit your content container.

6. Add your vector field(s) to the FieldsToinclude list.

   

7. Save the changes.

8. Validate that the vector fields are returned on the results:

   1. Open the dev tools for your browser.

   2. Navigate to the Network tab.

   3. Look for the search request.

   4. On the response, validate that the vector field was returned.

   

Deciding which type of search to use

There are multiple searches that can be executed against the Azure Search Index using Smart Hub Azure Search Engine:

In order to execute one of the above, you need to enable the components required in each of the cases to be included in the final search request.

• Full text component:

  • This is always enabled by default

  • Running searches without this component is not supported

• Vector query component:

  • This is enabled when the VectorQueries member of the Query object has at least one VectorQuery set; For more information on how to set VectorQuery, see How to Use Vector Search.

• Semantic Component

  • This is enabled by setting “Enable Semantic Search” to true in the Azure Query Translator stage

Troubleshooting

Check the server logs for any configuration errors. By default, logs appear in the directory <SmartHub_Install_Directory>\Logging.

Supplemental search engine

Bing News

About

Bing News search engine uses the News Search API to:

• Send search queries to Bing
• Receive a list of relevant news articles

How to Add the Bing News Search Engine to SmartHub

Use the following instructions to add the Bing News 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 dialogue box appears.
4. Select Type: Experimental
   
5. Enter a search engine name.
   
6. In the Search Engine field, select Bing News Experimental.
   
7. Enter your parameters as set and defined in the table below into the appropriate fields.
   
8. Click OK.

Parameters

Bing Search

About

The Bing Search search engine uses the Web Search API to:

• Send search queries to Bing
• Receive search results that include links to web pages, images, and more.

How to Add the Bing Search search engine to SmartHub

Use the following instructions to add the Bing Search Experimental 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 dialogue box appears.
4. Select Type: Experimental
   
5. Enter a Search Engine name.
   
6. In the Search Engine field, select Bing Search Exerimental.
   
7. Enter your Bing API Access Key (see below).
   
8. Click OK.

Parameters

CourtListener

• About CourtListener

• Limitations

• How to Set Up the CourtListener search engine

• Refiner Properties

• Sorting Properties

• Fielded Queries

About CourtListener

CourtListener is a free legal research website containing millions of legal opinions from federal and state courts.

• For more information see: https://www.courtlistener.com/

Limitations

The following features are unsupported by the CourtListener search engine:

• File Type refiners

• Multiple order properties

• Fuzzy search and proximity

• Related opinions

• Field boosting

How to Set Up the CourtListener search engine

Use the following topics to set up and configure your CourtListener search engine.

Add a New search engine to SmartHub

1. Start by opening your SmartHub Administration site: https://<SmartHubSite>:<port>/_admin.

2. Click Add New Search Engine to add your new CourtListener search engine. The Search Engine page appears.

3. In the Search Engine field, select Court Listener Experimental.

4. Complete the following fields on the page:

• Authentication Token:

  • The authentication token is available only when you are logged in to CourtListener.

  • The token can be obtained from https://www.courtlistener.com/api/rest-info/.

  • As CourtListener states, keep this token private, like a password.

• Max number of results for shallow refiners:

  • The number of results the search engine uses to build the refiners. This value is set to 100 by default.

  • The lower the value, the faster queries are performed.

    • Note this can result in a less precise refiner.

  • The higher the value, the slower queries are performed.

    • Note this can result in a more accurate refiner.

  • The value should be smaller than 1000, otherwise you may experience throttling or the thread may be aborted.

• Summary Max Length:

  • The maximum number of characters for excerpt. This value is set to 200 by default.

Verify the Required Pipeline Stages

After the search engine is configured, ensure the Property Mapper pipeline stage is configured for both the Query and Results tuning stages for your new CourtListener search engine. If these pipeline stages are missing, add them using the following steps:

1. Go to the General Settings page from the SmartHub Administration page: https://<SmartHubSite>:<port>/_admin

2. Select the CourtListener search engine you have just created.

3. Click Add a new Query Stage link.

4. In the newly opened window, select the Property Mapper stage from the Pipeline Stages drop-down.

5. Add a new name for this state.

6. In the Parameters text area, add the properties you want to map in the format described in the left panel.

7. Save and repeat these steps for the Result Pipeline stage.

Refiner Properties

The results can be refined by the following properties:

• court_id – Facet Type: List facet

• judge – Facet Type: List facet

• dateFiled – Facet Type: Date picker facet

• citeCount – Facet type: Slider facet

• status_exact – facet type: List Facet

Default Refiners

• No default refiners are mapped.

• Remove Author, File Type, and Modified Date and add refiners from the above list

Sorting Properties

The Court Listener search engine supports sorting by only one property at one time. The properties that can be used for sorting are:

• Rank (default)

  • Descendent only

  • Note: An ascending order automatically results in a descending order.

• dateFiled

  • Ascendent

  • Descendent

• citeCount

  • Ascendent

  • Descendent

Fielded Queries

In addition to being able to place fielded searches in the side bar, advanced users can also place fielded searches in their main query.

For example:

• court_id:ca1 status:precedential

  • A search for court_id:ca1 status:precedential returns only:

    • precedential cases (status:precedential) in the First Circuit of Federal Appeals (court_id:ca1)

    • The Abbreviation field is used as the value for court_id field query.

• caseName:”Axe Tool Co.”

  • A search for caseName:”Axe Tool Co.” returns only:

    • cases that contains Axe Tool Co. in case name

• docketNumber:”1107”

  • A search for docketNumber:”1107” returns only:

    • cases that contains 1107 docket number.

More Information

• For more information about advanced query techniques see: https://www.courtlistener.com/help/search-operators/#fielded-queries-fieldname-term

• For all available jurisdictions see: https://www.courtlistener.com/api/jurisdictions/

Documentum

• About

• Prerequisites

• Authentication

• How to Install the Documentum Search Engine

• Configure Results Page

About

OpenText Documentum is an Enterprise Content Management system.

• The Documentum search engine makes it possible to search in SmartHub for documents stored on the OpenText Documentum server.

Prerequisites

The Documentum search engine is based on the Documentum REST API, therefore all the following must be satisfied:

• Documentum can be reached over the network from the machine where SmartHub is deployed.
• Search service is installed and configured in Documentum.
• REST API for Documentum is enabled.

Authentication

• Authentication of search engine is based on Azure applications.

• Both Documentum and SmartHub must be configured to support this type of authentication.

• When a user logs in to SmartHub, the authentication token of its application is automatically converted to a Documentum-related one and is used to authenticate in Documentum.

How to Install the Documentum Search Engine

1. Start by opening your SmartHub Administration site: https://<SmartHubSite>:<port>/_admin.
   
2. Click Add a New Search Engine. The search engine settings page appears.
3. Select Type: Experimental.
   
4. In the Search Engine field, select Documentum Experimental.
   
5. Complete the following fields on the page:
   • Base Url:
     • Base URL of Documentum REST API.
     • Example: http://mydocumentum.mydomain.com/dctm-rest
   • Scope URL
     • The scope URL configured in Azure application created for Documentum
   • Repository:
     • Name of Documentum repository to search
   • Date Refiner Format:
     • Select what refinement values to display for dates.
     • Possible values: "year", "quarter" and "month"

Configure Results Page

Refiners

Following properties can be used in refiners:

• ContentType
• All Documentum properties that support facets.

Configuring Refiners

• Following attributes must be set on each refiner in Results.html:
  • data-preload-values=”true” 
  • data-use-and="true"
• Properties filetype and a_content_type should not be used for refiners.
  • Use contentType property instead. 
• File {SmartHubFolder}\modules\SmartHubResourceLoader\DefaultModuleSettings.js must be changed.
  • Refiner mapping under query suggestions for filetype property must be either removed or changed to contentType.
• Date refiners must be configured as normal, text based refiners.
  • Refinement values are displayed according to the "Date Refiner Format" setting (see above)

Egnyte

• About Egnyte

  • Prerequisites

  • Limitations

• Create an app registration in Egnyte

• How to Set Up the Egnyte Search Engine

• Query Scripting Processor Tuning Stage

• Configure Your SmartHub Results Page

  • Refiner Properties

  • Sorting Properties

About Egnyte

Egnyte is a secure content platform.

• For more information about Egnyte, see: https://www.egnyte.com/solutions/secure-enterprise-content-platform
• For information about Egnyte apps and API, see Egnyte Help.

Prerequisites

• You must create your own app registration in Egnyte. Whn you add you Egnyte search engine, you will have to specify those parameters.

Limitations

The following limitations of the Egnyte search engine are due to the current Egnyte API:

• Egnyte API returns a maximum of 20 results.
  • BA Insight recommends you remove the "total results count" from the Results page.
• Egnyte API accepts queries that are up to 100 characters.

• Sorting can only be done by one property at one time. Properties that can be used for sorting are:

  • name
  • score
  • last_modified
  • size

• Highlighting doesn't work with custom fields. It is predefined by the Egnyte API.

• Excluding refiners:

  • Custom fields cannot be used for exclusion

  • Built-in properties that can be used for exclusion include fileName, folderName, canonicalFileName, canonicalFolderName, content, comments, description, size, modifiedDate, fileExtension, userName, userFullName, type.

Create an app registration in Egnyte

1. Go to developers.egnyte.com

2. Click SIGN IN.

3. You must Register if you do not already have an account.

4. Next, click Get API Key from the top of the page.

5. Click the APPLICATIONS tab.

6. Click CREATE A NEW APPLICATION.

7. Complete the fields with the following information:

   1. Name This is the name of your Egnyte application. Enter an appropriate name and note it for later use.

   2. Type: Publicly Available Application.

   3. Current User Base: New App (only for deployment, it is changed later)

   Note: Note: When you move to production we recommend you CHANGE this value to a more appropriate option for your environment, such as 100k-1m, etc..
   This impacts volumes and scalability

   4. Platform: Web App

   5. Egnyte domain you will use for testing: This is the name of your (client) domain in Egnyte. For example, app4domain

   6. App Icon URL: skip this field.

   7. Please describe what your application will do: This is a description of what you app will accomplish. You may complete this field as you see fit.

   8. Registered OAuth redirect URI:

      • Enter URL in the form: <URL of your domain>/oauth.

      • Example: https://app4YourDomain.egnyte.com/oauth

8. Click Register Application.

9. The App Registered page appears.

   

10. Your Key and Secret appear on this page. You should Record both of these values for the following use:

    1. Key is your Client ID for SmartHub usage.

    2. Secret is your Client Secret for SmartHub usage.

How to Set Up the Egnyte Search Engine

Use the following topics to set up and configure your Egnyte search engine.

Add a New Search Engine to SmartHub

1. Start by opening your SmartHub Administration site: https://<SmartHubSite>:<port>/_admin.
   
2. Click Add New Search Engine. The Search Engine page appears.
3. Select Type: Regular.
   
4. In the Search Engine field, select Egnyte.
5. Complete the following fields on the page:
   1. Egnyte Impersonation Property:This is the name of a property to be added to the client context properties that hold the username of the user to be impersonated. This is done with a script in a Query Scripting Processor tuning stage, see section Tuning Stages below.
      Note: The script retrieves the Client Context object and uses the upn property to calculate the user name of the logged user (without the domain) and add it to the Client Context in the custom property mentioned above.
      Note: If your Client Context object (JTW Token) contains a property of the logged user, without the domain, only the username, and the same username can be found in the Egnyte App, you no longer need the Scripting Tuning stage. The specific Client Context object (JTW Token) property must be added here.
   2. Name: This is the name you give to your Egnyte search engine.
   3. Domain: This is the Egnyte domain you want to search. For example: myegnyteapp.egnyte.com
   4. Folder Path (optional): This is the Egnyte folder path that you want to search. For example, /Shared/Templates.
   5. Client Id: This is the Client ID provided when creating an Egnyte app. See Egnyte Prerequisites.
   6. Client Secret: This is the Client Secret provided when creating an Egnyte app. See Egnyte Prerequisites.
      
6. Click the Get Authorization Code button. This opens and redirects you to a new web page.
   
   1. On the new page, enter your credentials.
      
      
      
   2. After logging in, you are redirected to a page where you grant access to the Egnyte app.
      
      
      
7. Click Allow Access. You are redirected to a new page.
   

8. In the URL of the new page, select the code parameter value.

   The value is found in the URL between the words "code=" and "&state":
   
   

   Note: This page may display "Not found". This is acceptable as long as the code parameter is shown in the URL.
   

9. Copy the code.
   
10. Go back to the Search Engine page and paste the code in the Authorization Code field.
    
11. Press the Get Access Token button.
    

12. You are redirected to a new page where you can see the Access Token.
    
    

    Note: As described in the Refresh Token section, a refresh token is not required.

13. Copy the access token using the "Copy to clipboard" button.
    
14. Go back to the Search Engine page and paste the access token in the Access Token field.
    
15. Click the Save button.
    
16. Close all web pages opened during the authentication process.

Verify the Required Tuning Stages

After the search engine is configured, ensure the Property Mapper tuning stage is configured for both the Query and Results tuning stages for your new Egnyte search engine. If these tuning stages are missing, add them using the following steps:

1. Go to the General Settings page from the SmartHub Administration page: https://<SmartHub_web_app_url>/_admin.
   
2. Select the Egnyte search engine you have just created.
   
3. Click ADD QUERY TUNING.
   
4. In the newly opened window, select the Property Mapper stage from the Pipeline Stages drop-down.
   
5. Add a new name for this state.
   
6. In the text area on the right, add the properties you want to map in the format described on the left panel. 
   
7. Save and repeat these steps for the Result Tuning stage.

Query Scripting Processor Tuning Stage

Next, a Query Scripting Processor stage should also be present as a Query tuning stage.

This stage adds a custom property to the Client Context object with the same name as the one you selected during Configuration step 5, for the field Egnyte Impersonation Property.

The script retrieves the Client Context object and uses the upn property to calculate the user name of the logged user (without the domain) and add it to the Client Context in the custom property mentioned above.

Note: The default script should resolve the Azure AD and Windows authentications. If a different type of authorization is used, then the script might have to be changed.

Configure Your SmartHub Results Page

1. Your SmartHub Results page is controlled by the file Results.html (or a modified version of that file if you use a custom Results page). Open your Results HTML page to edit.
   

2. Reference the Egnyte search engine name within a coveo-tab-section. See the example below:

   Example:
   

Refiner Properties

The results can be refined by the following properties:

• fileName
• size (only with a range operator)
• modifiedDate (only with a range operator)
• fileExtension
• userName
• userFullName
• Every custom metadata created in the source system.

  • To add custom metadata as a refiner, add the custom metadata to the PropertyMapper Tuning stage in your search engine using the specific format: dataFieldValueFromFacet,namespace.propertyName

    
    

    • Custom metadata: "Company"

    • Namespace where custom metadata is defined: "SHProd"

    • Data-Field configured in HTML page for your facet: "company"

    • PropertyMapper stage configured for Egnyte search engine:

Default Refiners

Sorting Properties

As mentioned in the limitation section, the Egnyte search engine supports sorting by only one property at one time.

The properties that can be used for sorting are:

• name

• score

• last_modified

• size

iManage Cloud

• Prerequisites

• Limitations

• Endpoints

• Required User Access and Authorization

• How to Configure an iManage Search Engine

  • Available Filters

  • Configuring Clicking Results Behavior

Prerequisites

• Network service account

Limitations

Note the following limitations before configuring your iManage Cloud search engine:

• The iManage federated search API only returns a maximum of 500 potential search results rather than a specific count. If your count of potential search results exceeds 500, the UI on the SmartHub results page will only state Results 1-10 of 500.

• Filtering is limited with the iManage search engine. You are able to filter integer-based values, such as a client number, but you cannot filter string-based values, such as client name.

• iManage search results do not return a hit highlighted summary. Text that precedes and succeeds the queried term is not included in the search results text block.

• Search queries that use trailing wildcards(*), for example, "litiga*", are not supported.

• The iManage search results do not return a score or rank.

• Relevancy tuning to dynamically weigh the importance of search results from specific search engines, is not supported by the iManage search engine.

• The iManage API does not return the refiners count. Instead, SmartHub computes the count based on the retrieved results. If your query returns more than 500 results (the iManage API search limit), the refiner count will not be accurate.

Endpoints used

These are the iManage service endpoints that the search engine uses:

• AUTHORIZE ENDPOINT = {iManageServerURL}/auth/oauth2/authorize

• TOKEN EXCHANGE ENDPOINT = {iManageServerURL}/auth/oauth2/token

• API INFO ENDPOINT = {iManageServerURL}/api

• SEARCH ENDPOINT = {iManageServerURL}/api/v2/customers/{customerID}/documents/search

Required User Access and Authorization

• This search engine implements Federated Impersonation which means every user must log in for themselves.

• You must configure the Federated Impersonation module to handle automatic user login before proceeding.

• The authentication flow is as follows:
  
  • The user is redirected to iManage where he provides credentials to log in.
  • iManage redirects him back to SmartHub.
  • The user is provided only with the items for which he has access to in iManage.

How to Configure an iManage Search Engine

1. Navigate to the SmartHub Administration page at: http(s)://[web-app-url]/_admin
   1. For example: http://smarthub.azurewebsites.net/_admin
      
2. Go to the General Settings page.
   
3. Add New Search Engine: Click the "Add New Search Engine" link to add your new iManage search engine.
4. Type: Select regular
   
5. In the Search Engine field, select iManage Cloud.
   
6. Next, enter the Name and corresponding information in the appropriate fields.
7. If you desire, you can use your own iManage App registration, however, this is not recommended. Upland BA Insight recommends using the default app registration. For more information, see the note regarding redirect URLs above.
Note: When registering the app you need some specific Redirect URLs.

Use the following table:

Available Filters

WorkspaceId, Author, Type, EditDateFrom, EditDateTo, CreateDateFrom, CreateDateTo,
Custom1 to Custom20, Custom29, Custom30

Note: Additional filters can be added if considered relevant (detailed list here)

Configuring Clicking Results Behavior

• Single-click
  • Opens the document in a new tab in iManage preview
• Double-click
  • Opens the document in the native app for that document type.
  • For example: Word for documents, PowerPoint for Presentation, etc

• The following products must be installed in your environment for this behavior to work:
  • iManageAgentServices
  • iManageWorkDesktopforWindows
  • Office Suite

Procedure:

Use the following steps to configure your iManage results clicking behavior:

1. Go to iManage search engine settings.
2. In the Document Profile Fields field, add the characters "iwl".

3. In your SmartHub settings file, and add FieldsToInclude from ContentContainers to the MainResults "iwl" property

4. Inside the MainResults option from ContentContainers:

Replace the last return:

"return SH.RootLevelURL + "/modules/ContentContainers/templates/iManageResultItemTemplate.html";"

With the following code:

"return SH.RootLevelURL + "/modules/ContentContainers/templates/iManageResultItemTemplate.html";"

iManage Server

• Prerequisites

• Limitations

• Endpoints

• Required User Access and Authorization

• How to Configure an iManage Search Engine

  • Available Filters

Prerequisites

• Network service account

Limitations

Note the following limitations before configuring your iManage Cloud search engine:

• The iManage federated search API only returns a maximum of 500 potential search results rather than a specific count. If your count of potential search results exceeds 500, the UI on the SmartHub results page will only state Results 1-10 of 500.

• Filtering is limited with the iManage search engine. You are able to filter integer-based values, such as a client number, but you cannot filter string-based values, such as client name.

• iManage search results do not return a hit highlighted summary. Text that precedes and succeeds the queried term is not included in the search results text block.

• Search queries that use trailing wildcards(*), for example, "litiga*", are not supported.

• The iManage search results do not return a score or rank.

• Relevancy tuning to dynamically weigh the importance of search results from specific search engines, is not supported by the iManage search engine.

Endpoints used

These are the iManage service endpoints that the search engine uses:

• AUTHORIZE ENDPOINT = {iManageServerURL}/auth/oauth2/authorize

• TOKEN EXCHANGE ENDPOINT = {iManageServerURL}/auth/oauth2/token

• API INFO ENDPOINT = {iManageServerURL}/api

• SEARCH ENDPOINT = {iManageServerURL}/api/v2/customers/{customerID}/documents/search

Required User Access and Authorization

• This search engine implements Federated Impersonation which means every user must log in for themselves.
• You must configure the Federated Impersonation module to handle automatic user login before proceeding.
•  The authentication flow is as follows:
  
  • The user is redirected to iManage where he provides credentials to log in.
  • iManage redirects him back to SmartHub.
  • The user is provided only with the items for which he has access to in iManage.

How to Configure an iManage Search Engine

1. Navigate to the SmartHub Administration page at: http(s)://<web-app-url>/_admin
   1. For example: http://smarthub.azurewebsites.net/_admin
      
2. Go to the General Settings page
   
3. Add New Search Engine: Click the "Add New Search Engine" link to add your new iManage search engine.
   
4. Type: Select Regular.
5. In the Search Engine field, select iManage Server.
   
6. Next, enter the Name and corresponding information in the appropriate fields. See the table below.

Use the following table:

Available Filters

WorkspaceId, Author, Type, EditDateFrom, EditDateTo, CreateDateFrom, CreateDateTo,
Custom1 to Custom20, Custom29, Custom30

Microsoft Academic Knowledge

• About

• How to Attain a Subscription Key

• Add a Microsoft Academic Knowledge Search Engine to SmartHub

  • Parameters

About

Microsoft Academic Knowledge search engine uses the Academic Knowledge API to interpret the user queries for academic intent and retrieve rich information from the Microsoft Academic Graph (MAG). For more information about the Microsoft Academic Knowledge project, see here in the Microsoft documentation.

How to Attain a Subscription Key

You enter your Microsoft subscription key into the search engine. This key is used to run authorized calls against the API.

1. If you don't have an account yet, click here to sign up.
2. Once this step is completed, go here to subscribe.
3. Once this process is completed, you are taken to your account page where you can copy the subscription key:

Add a Microsoft Academic Knowledge Search Engine to SmartHub

Use the following instructions to add the Microsoft Academic Knowledge 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 dialogue box appears.
4. Select Type: Regular.
   
5. Enter a search engine name.
   
6. In the Search Engine field, select Academic Knowledge Experimental.
   
7. Enter your parameters as set and defined in the table below into the appropriate fields.
   
8. Click OK.
   

Parameters

Microsoft Search Items

• About

• Limitations

• Set Azure Active Directory Authentication

• How to Add the Microsoft Search Items search engine to SmartHub

• How to Register an App in Azure and Configure It

• Metadata

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.

• The DatePicker refiner will not work for site entity types if the start date and end date are set to auto. For example, <div class="CoveoFacetDatePicker" data-start="auto"data-end="auto" data-default-state="collapsed" data-title="Modified Date" data-field="@date" data-lookup-field="@date" data-available-sorts="occurrencesdescending,occurrencesascending,alphaascending,alphadescending" data-enable-settings="false"> </div>.

  • If you want to use the DatePicker refiner, you must set it to specific date. For example, <div class="CoveoFacetDatePicker" data-start="2000-01-01"data-end="2025-01-01" data-default-state="collapsed" data-title="Modified Date" data-field="@date" data-lookup-field="@date" data-available-sorts="occurrencesdescending,occurrencesascending,alphaascending,alphadescending"></div>

• 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.
• Microsoft Search Graph API does not support excluding refiners.

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

   • 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

In SmartHub 7.1, enhancements were made to flatten the specific properties received from the Microsoft Graph API. Depending on the Microsoft Graph response structure, this update may remove the need to map to the tree-based metadata structure from the Microsoft Graph API response. For example, refer to the following code sample for driveItem:

"hitId": "01PHA2IYQCMAFRO66NPFDJFIJ4DSU3RCHA",
"rank": 1,
"summary": "<c0>1</c0> {<c0>170B6002</c0>-<c0>CD7B</c0>-<c0>4679</c0>-<c0>92A1</c0>-<c0>3C1CA9B888E0</c0>},<c0>1</c0> <c0>22</c0> <c0>STS</c0>_<c0>ListItem</c0>_<c0>DocumentLibrary</c0><ddd/>",
"resource": {
    "@odata.type": "#microsoft.graph.driveItem",
    "size": 0,
    "fileSystemInfo": {
        "createdDateTime": "2025-05-21T13:24:03Z",
        "lastModifiedDateTime": "2025-05-21T13:24:03Z"
        },
    "listItem": {
        "@odata.type": "#microsoft.graph.listItem",
        "id": "170b6002-cd7b-4679-92a1-3c1ca9b888e0",
        "fields": {
            "id": "AAAAAJAQ92OSSERGvRIPCDjHckEHAIc6rUz16gNKkz9jW1poJXsAAAAAASUAAIc6rUz16gNKkz9jW1poJXsAA4OsY68AAA2",
            "size": 0,
            "createdBy": "Sample Name",
            "hitHighlightedSummary": "<c0>1</c0> {<c0>170B6002</c0>-<c0>CD7B</c0>-<c0>4679</c0>-<c0>92A1</c0>-<c0>3C1CA9B888E0</c0>},<c0>1</c0> <c0>22</c0> <c0>STS</c0>_<c0>ListItem</c0>_<c0>DocumentLibrary</c0><ddd/>",
            "hitHighlightedProperties": null,
            "rank": 638834321782235820,
            "author": "Sample Name",
            "lastModifiedTime": "2025-05-21T13:24:03Z",
            "contentType": "Folder",
            "mimeType": "Folder",
            "path": "https://baidev.sharepoint.com/sites/Eric1/TestSubSite1/SiteAssets/TestSubSite1 Notebook"
            }
        },
    "id": "01PHA2IYQCMAFRO66NPFDJFIJ4DSU3RCHA",
    "createdBy": {
        "user": {
            "displayName": "Sample Name",
            "email": "Sample@baidev.onmicrosoft.com"
        }
    },
    "createdDateTime": "2025-05-21T13:24:03Z",
    "lastModifiedBy": {
        "user": {
            "displayName": "Sample Name",
            "email": "Sample@baidev.onmicrosoft.com"
        }
    },
    "lastModifiedDateTime": "2025-05-21T13:24:03Z",
    "name": "TestSubSite1 Notebook",
    "parentReference": {
        "driveId": "b!S9rn_MkXxEWhYQ1Jg7nITybXyBY6rONBlVP2Baiz5uKZd5ZH8nNAQbmppPDCYW8H",
        "id": "01PHA2IYWXIKXITBTWG5HJQU7RSYRE7ETZ",
        "sharepointIds": {
            "listId": "47967799-73f2-4140-b9a9-a4f0c2616f07",
            "listItemId": "1",
            "listItemUniqueId": "170b6002-cd7b-4679-92a1-3c1ca9b888e0"
            },
        "siteId": "baidev.sharepoint.com,fce7da4b-17c9-45c4-a161-0d4983b9c84f,16c8d726-ac3a-41e3-9553-f605a8b3e6e2"
        },
    "webUrl": "https://baidev.sharepoint.com/sites/Eric1/TestSubSite1/SiteAssets/TestSubSite1 Notebook"
    }
}

When configuring the property mapper tuning stage, you now only need to provide the property names for driveItem and listItem fields, and externalItem properties for your mapping. For example, using the sample above, you would need to provide the following property names when mapping:

• summary

• size

• fileSystemInfo.createdDateTime

• HitHighlightedSummary

• lastModifiedTime

• createdBy.user.displayName

As you can see, properties belonging to listItem fields, such as HitHighlightedSummary and lastModifiedTime, do not require the full map to the tree-based metadata structure.

Microsoft Search Calendar

• About

• Limitations

• Set Azure Active Directory Authentication

• How to Add the Microsoft Search Calendar search engine to SmartHub

• How to Register an App in Azure and Configure It

About

Microsoft Search Calendar search engine uses the Graph API to search for event information in a user’s primary calendar using the following resource types:

• Calendar

Limitations

The following are limitations for the Microsoft Search Calendar 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 Calendar search engine.
• The Microsoft Search Calendar search engine can only return 10 events 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.
• Microsoft Search Graph API does not support excluding refiners.

Set Azure Active Directory Authentication

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

Client ID Requirements

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

• Microsoft Graph

  • Calendars.Read

How to Add the Microsoft Search Calendar search engine to SmartHub

Use the following instructions to add the Microsoft Search Calendar 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 "".
   
6. Enter Graph Url. For example, https://graph.microsoft.com
   
7. 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.

      8. 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.comand 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

      • Calendars.Read

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
      
   3. A Value is generated after you click Add.
      

Microsoft Search Emails

• About

• Limitations

• Set Azure Active Directory Authentication

• How to Add the Microsoft Search Emails search engine to SmartHub

• How to Register an App in Azure and Configure

About

The Microsoft Search Emails search engine uses the Graph API to search for information in Microsoft Outlook email massages using the following resource type:

• Message

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.
• In some scenarios, the total number of results that is returned by the Microsoft Graph API is incorrect. This may cause your results pagination to behave unexpectedly, such as incorrect total counts being displayed or miscalculated page numbers. For more information, see MS Graph search query searchHitsContainer Total incorrect and Microsoft Graph Search API response incorrect 'total' value in the Microsoft Q&A forums.
• Microsoft Search Graph API does not support excluding refiners.

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 ""
   
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:
         • 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 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.comand 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.
      

Microsoft Search Chat Message

• About

• Limitations

• Set Azure Active Directory Authentication

• How to Add the Microsoft Search Chat Message Search Engine to SmartHub

• How to Register an App in Azure and Configure It

About

Microsoft Search Chat Message search engine uses the Graph API to send search queries to Microsoft 365, search for information in email messages (body and attachments), and receive emails from user's own mailbox using the following resource type:

• chatMessage

Limitations

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

• Refiners are not supported.

• Microsoft Search Graph API does not support excluding refiners.

Set Azure Active Directory Authentication

You can set your authentication to Azure Active Directory in SmartHub as described here: Filters.

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
  • Chat.Read or Chat.ReadWrite
  • ChannelMessage.Read.All
    

How to Add the Microsoft Search Chat Message Search Engine to SmartHub

Use the following instructions to add the Microsoft Search Chat Message 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 dialogue box appears.
   
4. Enter a search engine name.
   
5. In the Search Engine field, select MS Search Chat Message.
   
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. 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: 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).
         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.comand 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 Permissions to 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

      • Chat.Read or Chat.ReadWrite

      • ChannelMessage.Read.All

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:
      1. Enter a name for the client secret.
      2. Note: The nameis your client secret
   2. Expires: Select the period until expires.
      
      
   3. A Value is generated after you click Add.
      

Microsoft Search Persons

• About token-based authentication

• Limitations

• Set passwords for built-in users

  • Client ID Requirements

• Create and Configure Your Kendra Search Engine

• How to Configure the SharePoint Online Search Engine

About

Microsoft Search Persons search engine uses the Graph API to search for information about a person from mail and contacts using the following resource type:

• Person

Limitations

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

• Wild querying is not supported by the Microsoft Search Persons search engine.

• Refiners are not supported by the Microsoft Search Persons search engine.

• Microsoft Search Graph API does not support excluding refiners.

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:

1. Microsoft Graph

• People.Read

• People.Read.All

How to Add the Microsoft Search Persons search engine to SmartHub

Use the following instructions to add the Microsoft Search Persons 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 dialog box displays.
   
4. Enter a search engine Name.
   
5. Select the search engine Type ""
   
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:
         1. Enter the Application ID from Azure App Registrations.
      2. Client Secret:
         1. Enter the Key's value from Azure App Registrations.
      3. Microsoft Login Endpoint:
         1. Example: https://login.microsoftonline.com
      4. Access Token:
         1. Enter the access token from SmartHub's OAuth page.

      5. Refresh Token:

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

         To get AccessToken and Refresh token, "Authorize" button must be clicked, but all 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.
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.comand 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

      1. People.Read

      2. People.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:
      1. Enter a name for the client secret.
      2. Note: The name is your client secret
   2. Expires: Select the period until expires.
      
   3. A Value is generated after you click Add.
      

NetDocuments

Use the following topics to connect your SmartHub instance to the NetDocuments search engine (search engine).

• Important Mentions and Limitations

• Prerequisites

• User Access Requirements

• Create and Configure Your Kendra Search Engine

• Logs

• Filters

• Filters

• Query Scripting Processor Tuning Stage

• How to Configure the SharePoint Online Search Engine

• How to Register an App in Azure and Configure It

• How to Show Personal OneDrive Documents

Important Mentions and Limitations

Please note the following limitations before configuring your NetDocuments search engine:

Note: A service account can only be used with a single SmartHub instance at any one time.

Prerequisites

To correct this, set the CoveoFacets components to data-preload-values="true". This is done to the following HTML pages in your site:

• The Results HTML page.

• The Custom Results HTML page.

• Any custom HTML page that use refiners.

User Access Requirements

NetDocuments security is performed using two methods:

• Security token authentication
• User account-level security trimming

After token authentication is performed, security trimming is performed against the active SmartHub user account.

• SmartHub users can only access the NetDocuments cabinets their account has permissions to on the NetDocuments side.
• The account used to configure token authentication is also used for security trimming.
  • This account must have admin access (be a cabinet administrator) to all the cabinets the NetDocuments search engine is to search.
  • See Verify Cabinet Administration Permissions below.
• Additionally, Administrator requirements, specifically, are specified below.

Administrator Requirements

• The user account that configures token authentication must be an Administrator on the NetDocuments cabinets being searched.

• The user must be a cabinet administrator
• Admin access to cabinets that will not be searched is not required.

• SmartHub requires the Admin user to have the following permissions:

  • Permission to retrieve cabinets

  • Permission to READ other user's details.

  • Specific endpoints used:

    "/v2/search";
    "/v1/User/cabinets";
    "/v1/User/{0}/info";

Verify Cabinet Administration Permissions

Verify the user account used the configure token authentication has cabinet administration permissions.

1. In NetDocuments, open a cabinet that will be indexed by the BA Insight NetDocuments search engine and searched by users.
   
2. Select the drop-down menu for the cabinet and select Cabinet Information.
   
   
3. The Cabinet administrator user accounts are shown listed here. See the image below.
   
   1. The user account used for token authentication MUST be shown in this list for each and every cabinet to be searched by the BA Insight NetDocuments search engine.

User Account Requirements

Security trimming is performed at the user account level.

• SmartHub users can only access the NetDocuments cabinets their account has permissions to on the NetDocuments side.
• Security trimming is performed by the NetDocuments search engine for the user account searching NetDocuments cabinets.
• A user's account must have permission to read from the NetDocuments cabinets to successfully search them.

Cabinets

• The cabinets you access must be in the same repository.

  • To search cabinets from multiple repositories you must configure a separate SmartHub NetDocs search engine for each repository.

• SmartHub only queries the cabinets the authenticated user account has access to (within NetDocuments).

How to Add a NetDocuments Search Engine

1. Navigate to the SmartHub Administration page at http(s)://[web-app-url]/_admin
   • For example: http://smarthub.azurewebsites.net/_admin .
     
2. From the General Settings page click Add New Search Engine to add your new NetDocuments search engine.
3. The Search Engine dialogue appears.
   
4. In the Type field, select Regular.
5. From the Search Enginedrop-down list, select NetDocs.
6. In the Name field, Enter a name for your search engine.
7. In the Rank offset formula coefficients field, enter values for the Boost and Offset. Enter these values only if you selected the Rank Based mixing algorithm that is set in the Properties for SSA page.
8. In the Data Center Region field, select your preferred data center from the drop-down list. The supported Data Center regions are: US, UK, DE, AU. The default data center is US.
9. In the Auth Provider Email field, enter the email property of your Authentication provider used for security trimming. This property must contain the NetDocs user email. When using AAD authentication, ensure that the email claim is added as an ID token.
   The default "upn" might not contain the email address of the user. See How to Configure Security Trimming for Windows Authentication for info about how to create a new claim which has the user's email.
10. In the NetDocuments Repositories field, enter a comma separated list of repositories. These repositories are used to make additional attribute requests to allow for deep search-within for NetDocuments description properties. If you do not configure this field, basic search-within functionality is applied.
11. In the Cabinets field, enter a comma separated list of cabinets to be used for search. You can also specify "*" to search all cabinets where the user has access to. The default value for this field is cabinet1, cabinet2.
12. In the Attributes to return field, enter a comma separated list of attributes to return from NetDocuments. The default value for this field is StandardAttributes, CustomAttributes, Locations, Descriptions, VersionsLite, CheckedOutBy, AllowCheckedOutState, EmailAttributes.
13. NetDocuments has identifiers for every search field. In the Facets field, you can map each facet on the page to its unique field identifier. The default value for this field is Ext,11;Modified,5;CreatedBy,6.
14. In the Supported Fields field, enter a comma separated list of the most common supported identifiers. If the field identifier is not found on this list, or isn't in XXXX format, the query will return 0 results. The default value for this field is 3,4,5,6,7,8,11,17,18,19,20,27,54,55,56,250,999.
15. If Search All Versions is enabled, the search matches a document if any of its versions contain the user search keywords. For more information, see How to Configure Multi-version Search.
16. Click Authorize, after you will be redirected to a NetDocuments page to provide credentials. See Authorization below.
    

Authorization

1. Use your NetDocuments account credentials to log in.

2. Click Allow to give the application full access to all resources.
   
   • Note: If you have multiple repositories, and you want results from all of them you must set up a different NetDocuments search engine for each repository.
     
3. Click Authorize.
   
4. Return to the SmartHub administration portal, and copy the code in the Authorization Code text box.
   
5. Click Get Access/Refresh Tokens . A new page will open with the Access and Refresh tokens.
   
6. Copy and paste the Access and Refresh tokens into the fields in the SmartHub administration portal.
   
7. Click the OK button.

How to Configure Security Trimming for Windows Authentication

After you have configured your NetDocuments search engine, as described above, use the instructions below to insert a script to enable SmartHub to trim query results according to each user's access rights.

1. Under Pipeline Stages for your NetDocuments search engine, select Add New Query Stage.
2. Select Query Scripting Processor.
   
3. Name the pipeline stage.
4. Leave the Referenced Assemblies and Imported Namespaces fields empty
5. Enter the following script in the Script field and replace the following variables with the appropriate values for you environment:
   1. var domainName:
      • Enter the URL of your domain inside quotes.
      • For example, "acmedomain.com"
   2. userContext.SetProperty():
      • This value ("netDocsEmail" in the code snippet below) can be any text.
      • This value needs to be added to the NetDocs Search Engine settings, replacing the already existing value in the Auth Provider Email property field.

      var userContext = BAInsight.Longitude.Federator.Runtime.Security.SecurityPermissions.Load() as BAInsight.SmartHub.Core.Security.Context.JWTUserContext;
      var domainName = "YourDomain.com"; // the domain of the user account
      var username = userContext.GetProperty("upn", ""); // this retrieves the user name
      userContext.SetProperty("netDocsEmail", username + "@" + domainName);  // this generates the user address in the required format: username@domain.com

6. Click OK to close the window.

How to Configure the Property Mapper with NetDocuments Properties

Perform the following steps to discover properties in NetDocuments that you can map in SmartHub:

1. Login to NetDocuments with an Admin account.
   
2. Access the Admin Console by clicking Admin from the top right drop-down menu.
   
3. Go to the Navigation menu (top left) and select Profile Attributes.
   
4. The Profile Attributes or similar window appears, as shown below:
   
   
   
5. Use the property names and numbers ("Id" column) shown here in the SmartHub Property Mapper.
   1. Examples: MatterId,1002;
   2. For nested profile attributes, you can reference them by their ID preceded by their parent ID.
      1. Examples: MatterId, 1001.1002;
      2. Note: Only parent-child attributes can be mapped. There is no support for parent-child-grandchild types.
   3. You can also use composed property mappings that point to the specific field(s) you want returned.
      For instance:
      • Value
        • Returns the value field of the property
          • Examples: ClientId, 1001.Value;
        • By default, properties will be linked to the Value field
          • "ClientId, 1001" is the same as "ClientId, 1001.Value"
      • Description
        • Returns the description field of the property
          • Examples: ClientName, 1001.Description;
        Important! NetDocs does not support "deep" search-within for Description properties.
        However, SmartHub will let you do a "shallow" search-within using the max number of facet values returned by NetDocs (top 100 values).
      • ValueAndDescription
        • Returns the description and value fields of the property with the format "description (value)"
          • Examples: Client, 1001.ValueAndDescription;
   4. Nested profile attributes can be used as composed property mappings as well, for any type of field:
      • Examples: Matter, 1001.1002.ValueAndDescription;
        
      • Note: If you are using composed property mappings, make sure that AttributesToReturn contain the Descriptions field.

6. You can add custom results properties in your custom settings file, under FieldstoInclude of the ContentContainers section:
   

   Custom Settings Example

   SH.ContentContainers = SH.ContentContainers || {};
   SH.ContentContainers.CustomSettings = {
       MainResults: {
           FieldsToInclude: 'clickUri,title,Rank,ContentSource,FileExtension,excerpt,SDFUrl,date,DisplayAuthor,isUserProfile,isAuth,isError,HitHighlightedSummary,WorkEmail,JobTitle,Department,AboutMe,escbasecrawurl,UserName,PictureUrl'
       }
   };

   1. Custom properties include:

      • Cabinets,Repositories,Url,Email,DocId,EnvId,DocNum

   2. For nested properties, like Versions, CheckedOut or Email, you can access them via Versions.Official or CheckedOut.Name.
      1. Versions accepted fields:
         • Annotations, AutoVersion, Count, LatestVersionLabel, LatestVersionNumber, Official, OfficialVersionLabel, OfficialVersionName, SearchInfo, TotalSize
         • Note: Make sure that AttributesToReturn contains the VersionsLite field.
      2. CheckedOut accepted fields:
         • Comment, Guid, Name, When
         • Note: Make sure that AttributesToReturn contains the CheckedOutBy,AllowCheckedOutState fields.
      3. Email accepted fields:
         • MessageId, Subject, From, To, CC, ConversationId, EmlConversationId, MessageClass
         • Note: Make sure that AttributesToReturn contains the EmailAttributes field.

Logs

By default, logs appear in the directory <SmartHub_Install_Directory>\Logging

How to Enable/Disable Hit-Highlighting 

1. Navigate to the SmartHub Administration page.
2. Select the NetDocuments search engine.
3. Modify the Property Mapper from both "Query Pipeline Stages" and "Results Pipeline Stages" sections by adding/removing the following mapping: excerpt,Highlight;
   
4. Save the change.
   
   

How to Overwrite the Search Query Flags 

1. Navigate to the SmartHub administration page.
2. Select the NetDocuments search engine.
3. Click Add New Query Stage.
4. From the dropdown select Query Scripting Processor.
5. Provide a name for this pipeline stage.

6. In the Script section add the following code:

   Script

   Query.ExtendedProperties.Add("NetDocsQueryFlags", "<custom_flags>");

   When "NetDocsQueryFlags" is present, the current flags are overwritten. This enables you to control different query flags that NetDocuments expects, such as AggregateResults when doing multi-version search.

7. Compile and Save.

How to Configure Multi-version Search

About

• When “Search All Versions” functionality is enabled, the search matches a document if any of its versions contain the user search keywords.

• The search engine returns the latest document version that matched the search keywords together with information about all the other versions that matched the user search keywords - as you can see in the JSON example below:

Sample - Multi-version JSON response 

{
    "TotalRelevantResults": 6,
    "TotalRelevantResultsIncludingDuplicates": 6,
    "TotalRelevantResultsRowCount": 1,
    "RelevantResults": [
        {
            "Properties": [
                {
                    "Name": "title",
                    "Type": "System.String, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089",
                    "Value": "animalTest",
                    "DateTimeMode": 3
                },
                {
                    "Name": "filetype",
                    "Type": "System.String, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089",
                    "Value": "docx",
                    "DateTimeMode": 3
                },
                {
                    "Name": "FileExtension",
                    "Type": "System.String, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089",
                    "Value": "docx",
                    "DateTimeMode": 3
                },
                {
                    "Name": "Size",
                    "Type": "System.String, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089",
                    "Value": "12324",
                    "DateTimeMode": 3
                },
                {
                    "Name": "date",
                    "Type": "System.String, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089",
                    "Value": "9/9/2022 10:39:56 AM",
                    "DateTimeMode": 3
                },
                {
                    "Name": "clickUri",
                    "Type": "System.String, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089",
                    "Value": "https://vault.netvoyage.com/neweb2/goid.aspx?id=4886-1104-6442&open=y&ver=9",
                    "DateTimeMode": 3
                },
                {
                    "Name": "Versions",
                    "Type": "System.String, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089",
                    "Value": "{\"Count\":15,\"Official\":15,\"OfficialVersionName\":\"v15\",\"OfficialVersionLabel\":\"15\",\"LatestVersionLabel\":[15,0],\"LatestVersionNumber\":15,\"AutoVersion\":false,\"Annotations\":false,\"Versions\":[{\"Number\":15,\"Label\":\"15\",\"IsLatest\":true,\"Created\":\"2022-09-09T10:39:56Z\",\"CreatedByGuid\":\"VAULT-18SI78J7\",\"Source\":14,\"Description\":\"\",\"Name\":\"v15\",\"Official\":true,\"Locked\":false,\"Ext\":\"docx\",\"Modified\":\"2022-09-09T10:39:56.524Z\",\"ModifiedBy\":\"Daniela Birsan\",\"ModifiedByGuid\":\"VAULT-18SI78J7\",\"DeliveryRevoked\":false,\"Annotations\":false,\"Search\":{\"Hit\":true,\"NameHits\":[],\"Snippets\":[]},\"Size\":12324},{\"Number\":14,\"Label\":\"14\",\"IsLatest\":false,\"Created\":\"2022-09-09T08:26:36Z\",\"CreatedByGuid\":\"VAULT-18SI78J7\",\"Source\":13,\"Description\":\"\",\"Name\":\"v14\",\"Official\":false,\"Locked\":false,\"Ext\":\"docx\",\"Modified\":\"2022-09-09T08:26:36.592Z\",\"ModifiedBy\":\"Daniela Birsan\",\"ModifiedByGuid\":\"VAULT-18SI78J7\",\"DeliveryRevoked\":false,\"Annotations\":false,\"Search\":{\"Hit\":true,\"NameHits\":[],\"Snippets\":[]},\"Size\":12236},{\"Number\":13,\"Label\":\"13\",\"IsLatest\":false,\"Created\":\"2022-09-08T14:29:34Z\",\"CreatedByGuid\":\"VAULT-18SI78J7\",\"Source\":12,\"Description\":\"\",\"Name\":\"v13\",\"Official\":false,\"Locked\":false,\"Ext\":\"docx\",\"Modified\":\"2022-09-08T14:29:34.794Z\",\"ModifiedBy\":\"Daniela Birsan\",\"ModifiedByGuid\":\"VAULT-18SI78J7\",\"DeliveryRevoked\":false,\"Annotations\":false,\"Search\":{\"Hit\":true,\"NameHits\":[],\"Snippets\":[]},\"Size\":12172},{\"Number\":12,\"Label\":\"12\",\"IsLatest\":false,\"Created\":\"2022-09-08T12:48:01Z\",\"CreatedByGuid\":\"VAULT-18SI78J7\",\"Source\":11,\"Description\":\"\",\"Name\":\"v12\",\"Official\":false,\"Locked\":false,\"Ext\":\"docx\",\"Modified\":\"2022-09-08T12:48:01.854Z\",\"ModifiedBy\":\"Daniela Birsan\",\"ModifiedByGuid\":\"VAULT-18SI78J7\",\"DeliveryRevoked\":false,\"Annotations\":false,\"Search\":{\"Hit\":true,\"NameHits\":[],\"Snippets\":[]},\"Size\":12106},{\"Number\":11,\"Label\":\"11\",\"IsLatest\":false,\"Created\":\"2022-08-31T08:58:59Z\",\"CreatedByGuid\":\"VAULT-18SI78J7\",\"Source\":9,\"Description\":\"\",\"Name\":\"v11\",\"Official\":false,\"Locked\":false,\"Ext\":\"docx\",\"Modified\":\"2022-08-31T08:58:59.529Z\",\"ModifiedBy\":\"Daniela Birsan\",\"ModifiedByGuid\":\"VAULT-18SI78J7\",\"DeliveryRevoked\":false,\"Annotations\":false,\"Search\":{\"Hit\":true,\"NameHits\":[],\"Snippets\":[]},\"Size\":12089},{\"Number\":10,\"Label\":\"10\",\"IsLatest\":false,\"Created\":\"2022-08-29T13:09:43Z\",\"CreatedByGuid\":\"VAULT-18SI78J7\",\"Source\":9,\"Description\":\"\",\"Name\":\"v10\",\"Official\":false,\"Locked\":false,\"Ext\":\"docx\",\"Modified\":\"2022-08-29T13:09:44.136Z\",\"ModifiedBy\":\"Daniela Birsan\",\"ModifiedByGuid\":\"VAULT-18SI78J7\",\"DeliveryRevoked\":false,\"Annotations\":false,\"Search\":null,\"Size\":12118},{\"Number\":9,\"Label\":\"9\",\"IsLatest\":false,\"Created\":\"2022-08-29T11:35:46Z\",\"CreatedByGuid\":\"VAULT-18SI78J7\",\"Source\":8,\"Description\":\"\",\"Name\":\"v9\",\"Official\":false,\"Locked\":false,\"Ext\":\"docx\",\"Modified\":\"2022-08-29T11:35:46.404Z\",\"ModifiedBy\":\"Daniela Birsan\",\"ModifiedByGuid\":\"VAULT-18SI78J7\",\"DeliveryRevoked\":false,\"Annotations\":false,\"Search\":{\"Hit\":true,\"NameHits\":[],\"Snippets\":[]},\"Size\":12122},{\"Number\":8,\"Label\":\"8\",\"IsLatest\":false,\"Created\":\"2022-08-29T07:48:24Z\",\"CreatedByGuid\":\"VAULT-18SI78J7\",\"Source\":6,\"Description\":\"\",\"Name\":\"v8\",\"Official\":false,\"Locked\":false,\"Ext\":\"docx\",\"Modified\":\"2022-08-29T07:48:24.536Z\",\"ModifiedBy\":\"Daniela Birsan\",\"ModifiedByGuid\":\"VAULT-18SI78J7\",\"DeliveryRevoked\":false,\"Annotations\":false,\"Search\":null,\"Size\":12088},{\"Number\":7,\"Label\":\"7\",\"IsLatest\":false,\"Created\":\"2022-08-23T13:38:08Z\",\"CreatedByGuid\":\"VAULT-18SI78J7\",\"Source\":6,\"Description\":\"\",\"Name\":\"v7\",\"Official\":false,\"Locked\":false,\"Ext\":\"docx\",\"Modified\":\"2022-08-23T13:38:08.401Z\",\"ModifiedBy\":\"Daniela Birsan\",\"ModifiedByGuid\":\"VAULT-18SI78J7\",\"DeliveryRevoked\":false,\"Annotations\":false,\"Search\":null,\"Size\":12052},{\"Number\":6,\"Label\":\"6\",\"IsLatest\":false,\"Created\":\"2022-08-09T13:07:50Z\",\"CreatedByGuid\":\"VAULT-18SI78J7\",\"Source\":5,\"Description\":\"\",\"Name\":\"v6\",\"Official\":false,\"Locked\":false,\"Ext\":\"docx\",\"Modified\":\"2022-08-09T13:07:50.223Z\",\"ModifiedBy\":\"Daniela Birsan\",\"ModifiedByGuid\":\"VAULT-18SI78J7\",\"DeliveryRevoked\":false,\"Annotations\":false,\"Search\":null,\"Size\":12086},{\"Number\":5,\"Label\":\"5\",\"IsLatest\":false,\"Created\":\"2022-08-08T14:12:16Z\",\"CreatedByGuid\":\"VAULT-18SI78J7\",\"Source\":4,\"Description\":\"\",\"Name\":\"v5\",\"Official\":false,\"Locked\":false,\"Ext\":\"docx\",\"Modified\":\"2022-08-08T14:12:17.106Z\",\"ModifiedBy\":\"Daniela Birsan\",\"ModifiedByGuid\":\"VAULT-18SI78J7\",\"DeliveryRevoked\":false,\"Annotations\":false,\"Search\":null,\"Size\":12098},{\"Number\":4,\"Label\":\"4\",\"IsLatest\":false,\"Created\":\"2022-08-05T10:42:31Z\",\"CreatedByGuid\":\"VAULT-18SI78J7\",\"Source\":3,\"Description\":\"\",\"Name\":\"v4\",\"Official\":false,\"Locked\":false,\"Ext\":\"docx\",\"Modified\":\"2022-08-05T10:42:31.557Z\",\"ModifiedBy\":\"Daniela Birsan\",\"ModifiedByGuid\":\"VAULT-18SI78J7\",\"DeliveryRevoked\":false,\"Annotations\":false,\"Search\":null,\"Size\":12065},{\"Number\":3,\"Label\":\"3\",\"IsLatest\":false,\"Created\":\"2022-07-21T11:33:15Z\",\"CreatedByGuid\":\"VAULT-18SI78J7\",\"Source\":2,\"Description\":\"\",\"Name\":\"v3\",\"Official\":false,\"Locked\":false,\"Ext\":\"docx\",\"Modified\":\"2022-07-21T11:33:15.125Z\",\"ModifiedBy\":\"Daniela Birsan\",\"ModifiedByGuid\":\"VAULT-18SI78J7\",\"DeliveryRevoked\":false,\"Annotations\":false,\"Search\":null,\"Size\":12038},{\"Number\":2,\"Label\":\"2\",\"IsLatest\":false,\"Created\":\"2022-07-21T11:30:52Z\",\"CreatedByGuid\":\"VAULT-18SI78J7\",\"Source\":1,\"Description\":\"\",\"Name\":\"v2\",\"Official\":false,\"Locked\":false,\"Ext\":\"docx\",\"Modified\":\"2022-07-21T11:30:52.874Z\",\"ModifiedBy\":\"Daniela Birsan\",\"ModifiedByGuid\":\"VAULT-18SI78J7\",\"DeliveryRevoked\":false,\"Annotations\":false,\"Search\":null,\"Size\":12022},{\"Number\":1,\"Label\":\"1\",\"IsLatest\":false,\"Created\":\"2022-07-21T11:24:49Z\",\"CreatedByGuid\":\"VAULT-18SI78J7\",\"Source\":0,\"Description\":null,\"Name\":null,\"Official\":false,\"Locked\":false,\"Ext\":\"docx\",\"Modified\":\"2022-07-21T11:25:23.124Z\",\"ModifiedBy\":\"Daniela Birsan\",\"ModifiedByGuid\":\"VAULT-18SI78J7\",\"DeliveryRevoked\":false,\"Annotations\":false,\"Search\":null,\"Size\":11991}],\"SearchInfo\":false,\"TotalSize\":181607}",
                    "DateTimeMode": 3
                },
                {
                    "Name": "Rank",
                    "Type": "System.Double, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089",
                    "Value": 0.0,
                    "DateTimeMode": 3
                }
            ],
            "FederatorMetadata": {
                "Federatorsearch engine": "netdocs",
                "FederatorPositionInsearch engine": 0,
                "Federatorsearch engineRank": 0.0
            }
        }
    ],
    "RelevantResultsProperties": {},
    "ResultBlocks": [],
    "RefinementResults": [],
    "EvaluationResults": [],
    "QueryTerms": {},
    "KeywordInformation": {
        "Key": "",
        "Value": ""    },
    "PerformanceInformation": {
        "search enginePerformance": [
            {
                "search engineName": "netdocs",
                "search engineTime": 893,
                "TotalTime": 893,
                "PipelinePerformance": {
                    "PipelinesPerformance": [
                        {
                            "Counters": {
                                "PropertyMapper_ProcessText_GetExpressionTree": 0,
                                "PropertyMapper_ProcessText_UpdatePropertyNames": 0,
                                "PropertyMapper_ProcessText_RenderExpressionTree": 0,
                                "PropertyMapper_Process_QueryText": 0,
                                "PropertyMapper_ProcessText_GetExpressionTree_1": 0,
                                "PropertyMapper_ProcessText_UpdatePropertyNames_1": 0,
                                "PropertyMapper_ProcessText_RenderExpressionTree_1": 0,
                                "PropertyMapper_Process_QueryTemplate": 0,
                                "PropertyMapper_MapProperties": 0,
                                "PropertyMapper_Process_ProcessCollapseSpecification": 0,
                                "PropertyMapper_Process_ProcessPropertyList": 0,
                                "PropertyMapper_Process_ProcessPropertyList_1": 0,
                                "PropertyMapper_Process_ProcessSortList": 0,
                                "PropertyMapper_Process_ProcessRefiners": 0,
                                "PropertyMapper_Process_ProcessRefinementFilters": 0,
                                "PropertyMapper_Process_CustomRefinementIntervals": 0,
                                "PropertyMapper_Process_HiddenConstraints": 0
                            }
                        }
                    ]
                },
                "Counters": {
                    "RunQuery_FederatedImpersonation": 0,
                    "RunQuery_SetLog4NetContext": 0,
                    "RunQuery_PrepareQuery": 0,
                    "RunQuery_SelectPipelineStages": 0,
                    "RunQuery_ExecuteQueryPipeline": 0,
                    "RunQuery_ExecuteResultsPipeline": 0,
                    "RunQuery_AddFederatorMetadata": 0,
                    "RunQuery_PerformanceInformation": 0,
                    "RunQuery_CleanLog4NetContext": 0,
                    "search engineThreadStart_WaitForRunQuery": 893,
                    "search engineThreadStart_OnAfterQueryExecution": 0
                }
            }
        ],
        "PipelinePerformance": {
            "PipelinesPerformance": []
        },
        "TotalTime": 0,
        "Observations": [
            "Slowestsearch engine: netdocs took 893ms"        ],
        "Counters": {
            "PreparingFederatorEngine": 0,
            "PreparingPipelineStages": 0,
            "ExecutedQueryPipelineStages": 0,
            "Preparingsearch engines": 0,
            "Querysearch engines_PrepareQueryForsearch engines": 0,
            "QueryAllsearch engines_Filtersearch engines": 0,
            "QueryAllsearch engines_search engineThreadCreationAndJoin": 894,
            "ReceivedResultsFromsearch engines": 895,
            "MixingResults": 0,
            "CloningQuery": 0,
            "ExecutedResultsPipelineStages": 0,
            "Pagination": 0
        }
    },
    "SuppressPagination": false,
    "IsNotFirstPage": false,
    "BelongToSingleSource": false,
    "TableCollectionProperties": {},
    "search engineName": "netdocs",
    "TableProperties": {},
    "PeopleSuggestions": [],
    "QuerySuggestions": [],
    "ResultSuggestions": [],
    "RefinementsInfo": {
        "RefinementsWithMoreValues": {}
    }
}

• If “Search All Versions” is enabled:
  • The URL of a returned document includes the version denoted by the presence of the URL query parameter: “&ver=”
    
  • Example:
    • https://vault.netvoyage.com/neWeb2/goId.aspx?id=4840-1183-7122&open=Y&ver=3
• If “Search All Versions” is not enabled:
  • The URL does not include the parameter: “&ver=”
    
  • Example:
    • https://vault.netvoyage.com/neWeb2/goId.aspx?id=4840-1183-7122&open=Y

Prerequisites

• The NetDocuments tenant used by the SmartHub search engine must have Search Versions functionality enabled.
• This is a separate NetDocuments feature that is not enabled by default.
• Make sure you have a Search Versions checkbox under the Everything field on the Advanced Search window in the NetDocuments search portal.

Enable/Disable "Search All Versions" functionality

1. Navigate to the SmartHub administration page.
2. Select the NetDocuments search engine.
3. In the search engine Settings modal window, enable/disable the Search All versions slider.
4. Click Save.

Generate Previews for Multi-version Search Results

Note: Starting with SmartHub 5.6, previews for NetDocuments documents will work only if you have installed SmartPreviews 3.3. 

Note: The URL format for NetDocuments documents has been changed in SmartHub 5.6. This means that document URLs are no longer backward compatible with previous versions of SmartHub, thus the Smart Previews “PreviewCache“ database is obsolete. You must regenerate Previews for NetDocuments documents. See How to Remove Previews from Your Configured Storage.

Online Generation

Smart Previews online preview generation will continue to work with Search All Versions, both enabled and disabled. 

Smart Preview Import Server rules are exclusive. This means that you cannot have both online preview generation and offline preview generation for the same category of documents

• Example: Documents that are under 5 MB.
  

When the Search All Versions search engine option is enabled and Smart Previews rules are set to do offline preview generation (you have previews generated at crawl time only for the official version of the document), you must configure Smart Previews to do online preview generation for the other versions of the document other than the official one.

• This is done through a SmartHub scripting stage.

• This stage forces the online preview generation for documents that are a version different from the official versions, by changing the “PreviewStatusValue” metadata to a value of 2 as described in the topic Filters.

Note: Generating previews on-demand for large documents might take a longer time. The Ul shows the info message “Generating preview for this document is taking longer than 10 seconds. Please check back in a few minutes.”. Both the message and the default UI timeout can be configured as described in the How to Add Smart Previews to Your Results Page.

Offline Generation

Offline Generation with Connectivity Hub and NullTarget

• Smart Previews offline preview generation will work ONLY for the “official” version of the NetDocuments documents.

• Generating previews for any non-official version is only possible on-demand. See the above section "Online Generation" for details.

Prerequisites

• Connectivity Hub must be installed and configured.
• NetDocuments Connector must be installed and configured.
• NetDocuments connection and content must be created.
• NullTarget must be created.

Configure Offline Generation

In order for previews to be generated offline (at crawl time) using NullTarget, use these steps:

1. Navigate to the Connectivity Hub home page.
2. Access the Metadata page of the NetDocuments content that uses NullTarget.
3. Create a new Text metadata:
   1. Title: PreviewUrl (do not change this name).
   2. Description: Add a description for this metadata.
      
      • For example: "The url used by Smart Previews to generate preview."
   3. Value:
      1. Select Define by script

      2. Add script:

         1. If "Search All Versions" is enabled, add a script that uses the display URL and changes it to contain the version number:
            Example: https://vault.netvoyage.com/neweb2/goid.aspx?id=4840-1183-7122&open=y&ver=3
            

            Dim url As String = Host.GetValue("spw_url")
            Dim new_url As String = url & "&ver=" & Host.GetValue("OfficialVersion")
            return new_url.ToLower()

            Note: If the display URL (escbase_url) property contains "api." you need to remove it from the URL.
            Example:
            

            Dim url As String = Host.GetValue("spw_url")
            Dim new_url As String = url.Replace("api.", "") & "&ver=" & Host.GetValue("OfficialVersion") 
            return new_url.ToLower()

         2. If "Search All Versions" is disabled, add a script that uses the display URL:
            Example: https://vault.netvoyage.com/neweb2/goid.aspx?id=4840-1183-7122&open=y

            Dim url As String = Host.GetValue("spw_url")
            return url.ToLower()

            Note: If the display URL (escbase_url) property contains "api." you need to remove it from the URL.
            Example:
            

            Dim url As String = Host.GetValue("spw_url")
            Dim new_url As String = url.Replace("api.", "") 
            return new_url.ToLower()

      3. Make sure that the returned URL is lowercase.
   4. Save.

How to Add/Configure a Multi-Version Template

When having the "Search All Versions" option enabled, you can configure your results to show the other versions that contain the keywords the user searched for, by following these steps:

1. Navigate to the directory <SmartHub_root>\modules\ContentContainers\templates..

2. Create a new HTML template for results with multiple versions.

   1. Use the out-of-the-box template file resultItemWithMultipleVersionsTemplate.html file as an example.

Template 

<div class="sh-result-item core-result">
    <div class="core-result-info-wrapper">
        <div class="core-info">
            <span class="access-required-lock" style="display:<%= result.accessrequired ? "inline-block" : "none" %>">
                <i class="sh-icon-button far fa-lock"></i>
            </span>
            <a class="sh-title-value sh-result-link analytics-track-openItem" target="_blank" href="<%= result.clickUri %>" title="<%= result.title %>"><%= result.title %>
            </a>
        </div>
        <div class="core-info widgets-placeholder">
            <div class="sh-field-value sh-result-item-summary">
                <div><%= result.excerpt %></div>
            </div>
        </div>
        <% var hasMultipleVersions = false;
        if (result.Versions) {
            var versions = JSON.parse(result.Versions);
            if (versions.Count > 1 && versions.Versions)
                hasMultipleVersions = true;
        }
        if (hasMultipleVersions) { %>
        <div class="core-info versions-info">
            <div class="versions-header" style="padding-bottom: 10px;" onClick="SH.$('.versions-content-<%= result.index %>').toggleClass('hidden'); SH.$('.versions-header-arrow-<%= result.index %>').find('i').toggleClass('fa-angle-down fa-angle-up')">
                <div class="versions-header-text" style="display: inline; padding-right: 10px; font-weight: bold;">Other versions</div>
                <div class="versions-header-arrow-<%= result.index %>" style="display: inline;"><i class="fas fa-angle-down"></i></div>
            </div>
            <div class="versions-content-<%= result.index %> hidden">
                <% versions.Versions.forEach (function (version) {
                    if (version.Search && version.Search.Hit === true) {
                        var newUrl = result.clickUri.substring(0, result.clickUri.indexOf("&ver=") + 5) + version.Label;
                        var isCurrent = version.Label === result.clickUri.substring(result.clickUri.indexOf("&ver=") + 5); %>
                        <div class="version-item" style="padding-bottom: 10px;">
                            <a href="<%= newUrl %>"> <%= newUrl %>  <%= isCurrent ? " (current)" : "" %></a>
                            <div  class="open-preview-version-button sh-float-right" onClick="if(typeof BAInsight.DocumentViewer !== &quot;undefined&quot; && BAInsight.DocumentViewer._isMobile) {clearTimeout(BAInsight.LongitudePreview.HoverTimeoutId);} BAI.SmartPreviews.ShowDocumentPreview(&quot;<%= encodeURIComponent(newUrl)%>&quot;, &quot;<%= encodeURIComponent(newUrl)%>&quot;, &quot;<%=encodeURIComponent(result.title)%>&quot;, &quot;<%=Coveo.state(SH.utils.getSearchRoot(), "ql")%>&quot, SH.SmartPreviews.Options)">
                                <i class="sh-icon-button far fa-eye"></i>
                                <span>Preview version</span>
                            </div>
                        </div>
                    <% } %>
                <% }) %>
            </div>
        </div>
        <% } %>
        <div class="sh-action-bar core-action-bar">
            <a class='sh-result-link prettyURL sh-float-left' target="_blank" href="<%= result.clickUri %>" data-interception="off">
                <span title="<%= (result.filetype||'document') + " from " + (result.contentsource || result.clickUri || 'Source') %>"><%= (SH.utils.getSourceSystemImage(result.clickUri, result.ContentSource) || result.ContentSource) %></span>
                <span title="<%= result.clickUri %>"><%= SH.utils.prettifyURL(result.clickUri) %></span>
            </a>
            <div class="open-preview-button hidden sh-float-right" <% if(result.accessrequired) { %> style="display:none !important" <% } %> >
                <i class="sh-icon-button far fa-eye"></i>
                <span>Preview</span>
            </div>
        </div>
    </div>
</div>

3. Take the appropriate settings from the DefaultModuleSettings.js file (<SmartHub_root>\modules\SmartHubResourceLoader\DefaultModuleSettings.js), and copy them into your custom settings file.

4. Use <SmartHub_root>/modules/SmartHubResourceLoader/CustomSettingsTemplate.js as a template to create your custom settings file.

5. Change the ItemTemplatePicker setting to use the template created at step 2.

PubMed

• About token-based authentication

• Create and Configure Your Kendra Search Engine

  • Add an Elasticsearch Search Engine

  • Configure Scoring Profile In Azure

  • Results Page Example

• Security Trimming

About the PubMed Search Engine

PubMed comprises more than 30 million citations for biomedical literature from MEDLINE, life science journals, and online books.

• To learn more about PubMed, see https://www.ncbi.nlm.nih.gov/pubmed.

The following specific PubMed type search engines are available as search engines in SmartHub:

• NCBIPCCompound
• NCBIPCPathwayReaction
• NCBIPCSubstance
• NCBIPMC
• NCBIProtein

To set up PubMed as a search engine in your instance of SmartHub, use the topics below.

How to Set Up the PubMed Search Engine

Use the following steps to configure your PubMed search engine.

Add a New Search Engine to SmartHub

1. navigate to your SmartHub Administration site: https://<SmartHubSite>:<port>/_admin.
   
2. Click Add New Search Engine. The Search Engine page appears.
3. Type: Select Experimental.
4. In the Search Engine field, select your PubMed/PubChem search engine from the drop-down list. Refer to the list of search engines in the About section for more information.
   

5. Name: Enter a name for your PubMed search engine.

6. Maximum number of results to retrieve for a query: Enter a maximum number of results that you want to be retrieved for a query.

7. (Search Engine) API Key:
   1. When you register a new PubMed account, you are given the option to create a key.
   2. Use that key value here.
8. Supported result sources (optional):
   1. Add all the results sources where you want to display PubMed/PubChem content.
   2. Add the sources using the following syntax:
      1. Syntax: <Result source ID>=pccompound;<Result source ID>=pccompound;
      2. Example: 221c396f-c525-4fe2-a210-c58c81ffeb99=pccompound;661cca31-31ba-4021-9581-9b809a1a7faa=pccompound

Configure Your SmartHub Results Page

1. Your SmartHub Results page is controlled by the Results.html file, or a modified version of that file if you use a custom Results page.
   
2. Reference the PubMed/PubChem search engine name and the Result source ID (added to the search engine set up as above)
   1. Example:
      
      

PubChem Settings

If you are setting up PubChem you must also add code to your HTML page's custom settings file, (such as a custom Results page).

The fastest and easiest way to do this is using the UI Editor.

For information about how to access the UI Editor as well as who can access it, see How to Use the UI Editor.

1. From the SmartHub administration page, click UI Editor.

2. Click Select a page from the top menu.

3. Select the Results page

   1. BA Insight recommends you create your own custom page (and folder) to modify and leave the default files as templates. For example: MyResultsPage.html. For more information, see How to Create Custom Pages.

4. Select Advanced mode from top right.

5. Select Advanced settings edit.

6. Scroll down to the PubChem custom settings section around line 225:
   

7. Click the link See Default Settings in the top right corner. A new browser tab opens with the available custom settings.

8. Scroll down or search for "PubChem," around line 1045. Enable PubChem and the ChemComposer:

   1. Add all PubChem code from and including line 1047 to your custom settings file open in the previous tab.
   2. Change the following settings from "false" to "true":
      1. Enabled
      2. ChemComposerEnabled
         
         
9. Enable the PubChem Viewer.

   1. Scroll or navigate to the ContentContainers section in your custom settings file.

   2. Comment in the ContentContainers settings shown below, if necessary.

   3. Change the EnablePubChemViewer value from false to true. See below.
      
      

10. Click Save changes.

11. Click Preview<html_page>.html at the top of the code editor.

12. Review/test your changes in the tab that opens. Make any modifications back in the code editor.

13. Click Save changes when finished.

Example: PubChem Composer enabled in SmartHub:

Results Page Example

Once configured, your site Results page will resemble the screenshot below:

Security Trimming

Note: There is no security on PubMed content.

BA Insight SmartHub requires only an API key to access the content.

RightFind

• About token-based authentication

• Limitations

• Create and Configure Your Kendra Search Engine

  • Add an Elasticsearch Search Engine

  • Verify Cabinet Administration Permissions

• Configure Scoring Profile In Azure

  • Refiner Properties

  • Sorting Properties

About RightFind

RightFind Enterprise provides faster discovery and insights with immediate access to scientific literature and data and strengthens copyright-compliant collaboration.

• For more information see: http://www.copyright.com/business/rightfind/

Limitations

The RightFind search engine does not support:

• User Impersonation
• Support previews
• File Type and Modified Date refiners

How to Set Up the RightFind Search Engine

Use the following topics to set up and configure your RightFind search engine.

Add a New Search Engine to SmartHub

1. Navigate to your SmartHub Administration site:https://<SmartHubSite>:<port>/_admin.
   
2. Click Add New Search Engine.The Search Engine page appears.
3. Type: Select Experimental.
4. Search Engine: Select RightFind Experimental from the drop-down list.
5. Max number of results for shallow refiners: Specify the number of results the search engine uses to build the refiners 
   • The lower the value, the faster queries are performed. Note this can result in a less precise refiner.
   • The higher the value, the slower queries are performed, Note this can result in a more accurate refiner.
6. Fields to query: The RightFind index fields to query, comma separated.
   • Default value: title,parentTitle,abstract.
   • The full set can be obtained by checking RightFind documentation,
7. RightFind Domain: The RightFind domain you want to search.
   • Example: www.myrightfinddomain.rightfind.com
8. User Email: The email of the user account that has access to all items.
9. Password: The password for the email above.
10. Access Token: The access token obtained after authenticating.
11. Refresh Token: The refresh token obtained after authenticating, used to refresh the access token when it expires.
    
12. Click Get Access Token. You are redirected to a newly opened web page.
    
    
    
13. Click Copy to clipboard to copy the access token .
    
14. Go back to the search engine Configuration page and paste the access token in the Access Token field
    
15. Repeat steps 6 and 7 for the Refresh Token.
16. Click Save.
    
17. Close the web page opened during the authentication process.

Verify the Required Pipeline Stages

After the search engine is configured, ensure the Property Mapper tuning stage is configured for both the Queryand Results tuning stages for your new RightFind search engine.

If these tuning stages are missing, add them using the following steps:

1. Go to the General Settings page from the SmartHub Administration page: https://<SmartHubSite>:<port>/_admin.
   
2. Select the RightFind search engine that you just created.
   
3. Click Add a new Query Stage.
   
4. In the newly opened window, select the Property Mapper stage from the Pipeline Stages drop-down.
   
5. Add a new name for this state.
   
6. In the Parameters text area on the right side, add the properties you want to map in the format described in the left panel. 
   
7. Save and repeat these steps for the Result Pipeline stage.

Configure Your SmartHub Results Page

1. Your SmartHub Results page is controlled by the Results.html file or a modified version of that file if you use a customResults page.
   
2. Open your Results HTML page to edit.
   
3. Reference the RightFind search engine name within a coveo-tab-section.
   See the example below:
   
   Example:

Refiner Properties

The results can be refined by the following properties:

• authors (string)
• publicationDate (string)
• title (string)
• genre (int)
• contentId (int)

Default Refiners

One default standard refiner is already mapped to the following property:

• Display Author → authors

Note: The "File Type" and "Modified Date" refiners will not work with the RightFind search engine.

When using only a RightFind search engine, it is advised to edit the Result.html file and remove the 2 refiners from the code. 

Sorting Properties

The RightFind search engine supports sorting by only one property at one time.

The properties that can be used for sorting are:

• title
• score
• pubYear

Setting up your Azure Cosmos search engine

Overview of Azure Cosmos DB as a Search Engine in SmartHub

Azure Cosmos DB is a globally distributed, multi-model database service designed for high-scale, low-latency applications. When used as a search engine in SmartHub, Cosmos DB provides a flexible, graph-friendly data layer that goes beyond traditional keyword search. By modeling content, entities, and relationships as interconnected data, SmartHub can build a Knowledge Graph that captures how information is related, not just where keywords appear. This enables richer contextual search experiences and supports advanced use cases that rely on understanding relationships between data.

Prerequisites

Note the following prerequsites:

• You must have access to an Azure Cosmos DB resource.

Add a Azure Cosmos DB search engine to SmartHub

Delete this text and replace it with your own content.

1. In the SmartHub Administration portal, click General Settings.
2. In the Search Engines section, click Add New Search Engine. The Search Engine page appears.
3. Select Type: Regular.
   
4. In the Search Engine field, select Azure Cosmos
5. In the Name field, enter a name for your Azure Cosmos search engine.

6. In the Rank offset formula coefficients field, enter values for the Boost and Offset. Enter these values only if you selected the Rank Based mixing algorithm that is set in the General Settings.

7. In the Host Name field, enter the endpoint URI of your Azure Cosmos DB account. This value can be found on the Keys page of your Azure Cosmos DB account.

8. In the Database Name field, enter the name of the Azure Cosmos database that stores your SmartHub search data. This must match an existing database in your Cosmos DB account.

9. In the Graph Name field, enter the name of the graph container in your Azure Cosmos database. This can be found in your database information in the Azure Cosmos Data Explorer.

10. In the Port Number field, enter the network port used to connect to your Azure Cosmos DB instance.

11. In the Access Key field, enter the primary access key used to authenticate SmartHub to your Cosmos DB account. This value can be found on the Keys page of your Azure Cosmos DB account.

12. In the Partition Key field, enter the partition key path that you defined for the graph container. This must match the partition key configured in your Azure Cosmos DB instance.

13. Click the Accept button.