NetDocuments Backend

Use the following topics to connect your SmartHub instance to the NetDocuments backend The search engine your SmartHub instance uses to perform queries. SmartHub can be configured to use more than one search engine. (search engine The search engine your SmartHub instance uses to perform queries. SmartHub can be configured to use more than one search engine.).

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

Limitations

  • Hit highlighting of terms in document titles is not supported.

  • Summary text exception: Searches of more than 7 words do not display summary text.

  • Search operators clientname and mattername are not supported.

User Access Requirements

NetDocs 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 backend 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 backend 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 backend.

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 backend 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 backend for each repository.

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

How to Add an NetDocuments Backend

  1. Navigate to the SmartHub Administration page at http(s)://[web-app-url]/_admin
  2. Go to the General Settings page.

     
  3. Click the "Add New Backend" link to add your new NetDocs backend.
  4. Next, enter the Backend Name and corresponding information in the appropriate fields.
    See the following graphic.

     
  5. Backend type: Select NetDocsBackend from the drop-down list.

Authorization

  1. Edit "Data Center Region" (Optional)
    1. If you are using the default Data Center (US) skip this step.
    2. If you are using a different Data Center, enter the appropriate value into the field.
      1. Supported Data Center regions are: US, UK, DE, AU.
      2. European users, use UK.
  2. Use your NetDocs account credentials to log in.
    IMPORTANT: Your user account MUST have Administrator permissions to all the NetDocuments cabinets to be searched.
  3. Click the "allow" button 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 NetDocs backend for each repository
  4. Click Authorize
  5. From the Configuration page, copy the code in the Authorization Code text box.
  6. Click Get Access/Refresh Tokens 
  7. Copy and paste the Access and Refresh tokens.
  8. Click the OK button.
    1. Rank offset formula coefficients (optional): Enter these values only if you selected the Rank Based mixing algorithm that is set in the Properties for SSA page:
    2. BOOST: Enter the boost factor.
    3. OFFSET: Enter the rank offset.

Use the following table to specify this code:

Property Required? Description Default Value
NetDocsServerAddress Yes

The URL of your NetDocs Cloud service instance.

Obtain this URL from your NetDocs Cloud provider.

https://vault.netvoyage.com/v2/search
AuthProviderEmailProperty Yes

The email property of your Authentication provider used for security trimming.

This property must contain the NetDocs user email.

Note: The default "upn" might not contain the email address of the user. See below for info about how to create a new claim which has the user's email.
upn
Cabinets Yes

Specify one or more comma (,) separated cabinets to be used for search.

You can also use "*" to search all cabinets where the user has access to.

cabinet1, cabinet2
AuthenticationToken Yes Authentication token to be used for search. authToken
AttributesToReturn Yes Specify what attributes to return from NetDocs. StandardAttributes,CustomAttributes,Locations,Descriptions,VersionsLite,CheckedOutBy,AllowCheckedOutState,EmailAttributes
Facets Yes

NetDocs has identifiers for every search field.

Map each facet on the page to its unique field identifier.

Ext,11;Modified,5;CreatedBy,6
Supported Fields Yes

List of the supported most common identifiers.

If the field identifier is not found on this list or doesn't have XXXX format, the query will return 0 results.

3,4,5,6,7,8,11,17,18,19,20,27,54,55,56,250,999

How to Configure Security Trimming for Azure AD Authentication

By default the user JWT token contains a "upn" claim which is used by the NetDocuments backend to read the user email. (See the info about AuthProviderEmailProperty above). 

  • In most cases the "upn" will be the same as the user's email address.
  • However, it is possible that they are different.
    • Example: "upn" might be jdoe@company.net but the actual email address is john.doe@company.com

In this scenario you need to add an extra claim to SmartHub authorization token. There are 2 ways to do this:

  1.  (Recommended) - Add an extra claim to the Azure App Registration used by SmartHub
    1. Connect to the Azure portal
    2. Go to Azure Active Directory → App Registrations and select the app used by SmartHub (check SmartHub Admin Security Settings to find out the client id of the app)
    3. Go to Token Configuration → Add optional claim → Select Id → Select "email" → Add
    4. Log out from SmartHub so that you force a new token generation
    5. In the NetDocs backend configuration change AuthProviderEmailProperty to "email"
  2. Use a Scripting Stage to add a claim with the email address
    1. If the user email is not part of a claim in Azure AD then you will need to manually compute it using a scripting stage.
    2. You can derive it from other claims, for example by combining "given_name" and "family_name" claims. 
    3. Check the below script example on how to add an optional claim via Scripting Stage

How to Configure Security Trimming for Windows Authentication

After you have configured your NetDocuments backend, 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 NetDocs backend, select "Add New Query Stage".
  2. Select Query Scripting Processor.
  3. Name the pipeline stage Pipeline stages offer uniformity to the end user. Various functions include mapping names and values to match local refinements..


  4. Referenced Assemblies and Imported Namespaces: Leave empty for this script.
  5. Enter the code in the code block below into the "Script" field.
    Enter the appropriate values for the following settings:

    1. var domainName:

      1. Enter your domain inside quotes "".

      2. For example, "acmedomain.com".

    2. userContext.Claims[]:

      1. This value ("netDocsEmail" in the code below) can be any text.

      2. Add this value to the NetDocs Backend settings by replacing the current value in the Auth Provider Email property field (see below "NetDocs Backend Settings").

        Copy
        var userContext = BAInsight.Longitude.Federator.Runtime.Security.SecurityUtil.Load() as BAInsight.Longitude.Federator.Common.Util.OAuthUserContext;
        char separator = '\\';
        int usernamePosition=1;
        var domainName = "YourDomain.com"; // the domain of the user account
        var username = userContext.Claims["upn"].Split(separator)[usernamePosition]; // this retrieves the user name
        userContext.Claims["netDocsEmail"] = username + "@" + domainName;  // this generates the user address in the required format: username@domain.com
        • NetDocs Backend Settings

  6. Click OK to close the window.

How to Configure the NetDocuments Properties to Return

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

  1. Log 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.
        That is, 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
        1. Examples: ClientId, 1001.Value;
        2. 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;
        • Important! NetDocs does not support deep search-within for descriptions. You can search-within the facet by using the value, but not the description. Example: "John Doe (123456)" will be returned if you search for "123" but not if you search for "Joh"
    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. For results properties, you can add custom ones in Results.html around line 117, under the data-fields-to-include attribute:


    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 contain the VersionsLitefield
      2. CheckedOut accepted fields:
        • Comment, Guid, Name, When
          Note: Make sure that AttributesToReturn contain the CheckedOutBy,AllowCheckedOutState fields
      3. Email accepted fields:
        • MessageId, Subject, From, To, CC, ConversationId, EmlConversationId, MessageClass
          Note: Make sure that AttributesToReturn contain the EmailAttributes field.

Query-time Boosting and Document Scores in NetDocs

Doing query time boosting in NetDocs will affect the comparative scores between the documents as opposed to increasing the score for the matching documents. 

Example:
A boost of 3 creates a score of 3.3090768 for the first document.
- The next document has a score of 0.051462993.
Boosting by 30 creates a score of 3.2334785 for the first document
- The next document the score is 0.005173501.
The difference between the numbers for boost of 30 is a factor of 10 between the first and second documents - as compared to boosting by 3.
- For the boosting process, it is based on the documents returned and the comparative numbers associated with the returned documents.

Logs

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

Important Mentions and other Limitations

  • Facets are limited to the top 100 values.
    • NetDocs search API does not return more than 100 values for a facet.
    • There is no way to paginate through the facet values.
  • All date refiners should be of type "CoveoFacet".

  • Put the following code snippet in Results.html (or your custom Results HTML file) if you want to use a date refiner :

Date Refiner Code Snippet:

Copy
<div class="CoveoFacet" data-default-state="collapsed" data-title="Modified Date" data-field="@date" data-lookup-field="@date" data-available-sorts="occurrences,alphaascending,alphadescending"></div>
  • "CoveoFacetSlider" is not supported for date refiners.
  • The Search Within Refiners feature only supports sequences of at least two characters
  • Search Within Refiners only works for queries on the value field of the property with one exception where it will match on the description field.
    • Check above for a detailed explanation on composed properties like:
      • 1010.Value, 1010.ValueAndDescription, 1010.Description 
  • To disable Search Within feature for a refiner add the data-enable-facet-search="false" attribute

How to Enable/Disable Hit-Highlighting 

  1. Navigate to the SmartHub administration page.
  2. Select the NetDocuments backend.
  3. Modify the Property Mappers from both "Query Pipeline Stages" and "Results Pipeline Stages" sections by adding/removing the following mapping: excerpt,Highlight;
  4. Save the changes.


How to Overwrite the Search Query Flags 

  1. Navigate to the SmartHub administration page.
  2. Select the NetDocuments backend.
  3. Click on the "Add New Query Stage" link.
  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

    Copy
    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 

Copy
{
    "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": {
                "FederatorBackend": "netdocs",
                "FederatorPositionInBackend": 0,
                "FederatorBackendRank": 0.0
            }
        }
    ],
    "RelevantResultsProperties": {},
    "ResultBlocks": [],
    "RefinementResults": [],
    "EvaluationResults": [],
    "QueryTerms": {},
    "KeywordInformation": {
        "Key": "",
        "Value": ""    },
    "PerformanceInformation": {
        "BackendPerformance": [
            {
                "BackendName": "netdocs",
                "BackendTime": 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,
                    "BackendThreadStart_WaitForRunQuery": 893,
                    "BackendThreadStart_OnAfterQueryExecution": 0
                }
            }
        ],
        "PipelinePerformance": {
            "PipelinesPerformance": []
        },
        "TotalTime": 0,
        "Observations": [
            "SlowestBackend: netdocs took 893ms"        ],
        "Counters": {
            "PreparingFederatorEngine": 0,
            "PreparingPipelineStages": 0,
            "ExecutedQueryPipelineStages": 0,
            "PreparingBackends": 0,
            "QueryBackends_PrepareQueryForBackends": 0,
            "QueryAllBackends_FilterBackends": 0,
            "QueryAllBackends_BackendThreadCreationAndJoin": 894,
            "ReceivedResultsFromBackends": 895,
            "MixingResults": 0,
            "CloningQuery": 0,
            "ExecutedResultsPipelineStages": 0,
            "Pagination": 0
        }
    },
    "SuppressPagination": false,
    "IsNotFirstPage": false,
    "BelongToSingleSource": false,
    "TableCollectionProperties": {},
    "BackendName": "netdocs",
    "TableProperties": {},
    "PeopleSuggestions": [],
    "QuerySuggestions": [],
    "ResultSuggestions": [],
    "RefinementsInfo": {
        "RefinementsWithMoreValues": {}
    }
}

Prerequisites

  • The NetDocuments tenant used by the SmartHub backend 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” check box under the “Everything” text box inside the “Advanced Search” dialog in the NetDocuments search portal.

Enable/Disable "Search All Versions" functionality

  1. Navigate to the SmartHub administration page.
  2. Select the NetDocuments backend.
  3. In the Backend Settings modal window, check/uncheck the "Search All versions" check box.
  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 Smart Previews “PreviewCache“ database is obsolete.
- Previews will need to be regenerated for NetDocuments documents.

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.

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

  • Therefore, when the "Search All Versions" backend 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 achievable through a SmartHub scripting stage that forces the online preview generation for documents that are another version than the official, by changing the “PreviewStatusValue” metadata to a value of 2 as described in the How to Overwrite Preview Status Value section.

Note: Generating previews on-demand for large documents might take a longer time.
- The UI will show 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 with ConnectivityHub and NullTarget

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

Prerequisite
  • Connectivity Hub installed and configured.
  • NetDocuments Connector installed and configured.
  • NetDocuments connection and content created.
  • NullTarget created.
Configure Offline Generation

In order for previews to be generated offline (at crawl time) using NullTurget you need to follow 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

          Copy
          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

          Copy
          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

          Copy
          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

          Copy
          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 SmartHub installation folder.
  2. Open your Results html page.

    Note: Do not modify the out-of-the-box Results.html file as it will be overwritten at upgrade time.
    For more information, see  How to Customize Your SmartHub User Interface.

  3. In the Center column section, locate the CoveoResultList element.

  4. Locate the result template that have the condition: data-condition="isUserProfile != 'true' (around line 146).
  5. Add the following code block after the widgets-placeholder element (around line 157):

    Template 

    Copy
    <% var hasMultipleVersions = false;
    if (raw.Versions) {
        var versions = JSON.parse(raw.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-<%= raw.index %>').toggleClass('hidden'); SH.$('.versions-header-arrow-<%= raw.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-<%= raw.index %>" style="display: inline;"><i class="fas fa-angle-down"></i></div>    </div>    <div class="versions-content-<%= raw.index %> hidden">        <% versions.Versions.forEach (function (version) {
                if (version.Search && version.Search.Hit === true) {
                    var newUrl = raw.clickUri.substring(0, raw.clickUri.indexOf("&ver=") + 5) + version.Label;
                    var isCurrent = version.Label === raw.clickUri.substring(raw.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(raw.title)%>&quot;, &quot;<%=raw.state.ql%>&quot;, SH.SmartPreviews.Options)">                        
                            <i class="sh-icon-button far fa-eye"></i>                        
                            <span>Preview version</span>                    
                        </div>                
                    </div>            
                <% } %>        
            <% }) %>    
        </div>
    </div><% } %>

    • The code block above is just an example.

    • You can modify and style the template to contain information as you desire.

  6. Save.