How to Configure the Onboarding Module

About

The Onboarding module enables SmartHub to interact with users the first time they visit the SmartHub site.

Tip: Important!

The module is loaded by default only on the Results HTML page.
If you have results from an iManage content source on your Index HTML page (Index.html, stored at the SmartHub root level) then you must additionally load the JavaScript file <SmartHub_root>/modules/Onboarding/Onboarding.js" on the Index page as well.

The Onboarding module is used to:

  • Display "one-time" information to end users
  • Collect information or feedback from users
  • Trigger additional flows when a specific event happens on the SmartHub page
    • Example: Show results on the SmartHub site page from a content source which requires the user to authenticate first.

Structure

  • The Onboarding module acts as a mini-framework which manages sub-modules
  • Sub-modules run in a predefined sequence based on specific triggers

General Options for Onboarding Module

Option Value Description

Enabled

Boolean

Default: false

If set to "true" it enables the sub-modules to load and trigger flows.

GenericDialogTemplatePath

String

Default: SH.RootLevelURL + "/modules/Onboarding/templates/GenericDialogTemplate.html"

Defines the path to the default template for the generic dialog.

To customize the template:

  1. Duplicate the existing template
  2. Modify it as you desire
  3. Point to the new template file using this option
OnboardingModules

Object

Default:

{
    "FederatedImpersonation": {},

    "SampleOnboardingModule": {}

}

This contains the definitions of all sub-modules.

Out-of-the-Box sub-modules are found under this option. 

Onboarding Sub-Modules

Sub-modules are managed by the Onboarding framework.

Each sub-module defines a flow which triggers when a specific event happens.

Federated Impersonation Sub-Module

This Onboarding module launches a configuration wizard whenever it detects that the page is attempting to show results from a Content Source (source system) which requires manual authentication.

Configuration Options

Option Value Description
Active

Boolean

Default: true
  • If set to "true"then the Federated Impersonation sub-module checks the results on the page for an "authorization required" result for a specific backend (such as iManage).
  • If such a result is discovered, then it shows a dialog to the user which guides them through the authentication process.
Priority

Number

Default: 1

Defines the priority of the module if multiple modules are set to trigger on the same page load.

  • Sub-modules with lower numbers run first.
Path

String

Default: SH.RootLevelURL + "/modules/Onboarding/OnboardingModules/FederatedImpersonationModule.js"

The path to the file which contains the implementation of the sub-module.

  • Loaded only if the sub-module is set to Active:true
ModuleSettings

Object

Default:

{
    Backends: {
        "iManage": {
            InfoMessage: "This page wants to show you <b>iManage</b> results. After you click \"Ok\" you will be asked to sign in to iManage.".toLocaleString(),
            AuthDialogTitle: "Sign-in required",

            TrySilentAuth: true,
            DismissMessage: "You will no longer be prompted to authenticate to <b>iManage</b>. You can change this setting by accessing <b>Remote Content Sources</b> under your <b>Personalization</b> options.".toLocaleString(),
            DismissDialogTitle: "Important!".toLocaleString()
        },
        "OtherBackendRequiringLogIn": {
            InfoMessage: "Message which informs the user about the need to authenticate".toLocaleString(),
            AuthDialogTitle: "Sign-in required",
            DismissMessage: "Message that will appear if the user dismissed the authentication modal.".toLocaleString(),
            DismissDialogTitle: "Important!".toLocaleString()
        }
    }
}

These are settings particular to each sub-module.

The Federated Impersonation sub-module has the following custom settings:

Backends: A single collection of all the Content Source names (backends) that require authentication:

  • iManage:
    • This is the out-of-the-box backend which requires authentication.
    • If you named your iManage backend a name other than "iManage" then adjust the configuration.
      • TrySilentAuth:
        • If set to "true" then the confirm dialog will not appear
        • The user will be redirected directly to iManage and back
        • This is useful if you have multiple backends.
        • If the authentication process fails, then the user is shown the confirm dialog.
      • InfoMessage:
        • The first message that the end user sees when the module detects that additional authentication is required
      • AuthDialogTitle:
        • The title of the initial dialog (info dialog)
      • DismissMessage:
        • The message that appears if the user dismisses the dialog by clicking on the "x" button
      • DismissDialogTitle:
        • The title of the second dialog (dismiss dialog)

  • OtherBackendRequiringLogIn:
    • This is an example of how to add a second backend that requires user authentication

How to Customize the Onboarding Module

Overview

Like any SmartHub module, the Onboarding module is found in the directory <SmartHub_root>/modules.

The Onboarding module configuration is stored in the file DefaultModuleSettings.js (found in the directory <SmartHub_root>/modules/SmartHubResourceLoader) around line 1387.

Customization Steps

To customize the Onboarding module use the following steps:

  1. Open the DefaultModuleSettings.js (found in the directory <SmartHub_root>/modules/SmartHubResourceLoader).
  2. Open your Custom Settings file (typically, a renamed version of the template CustomSettingTemplate.js) for editing.
  3. In the file DefaultModuleSettings.js,navigate to the Onboarding settings, around line 1387.
  4. Copy the file Onboarding settings (shown above from line 1389 to 1421).
  5. Paste the settings into your Custom Settings file, inside the brackets of the line: "SH.Onboarding.CustomSettings = {};".
  6. Uncomment the Onboarding section in your Custom Settings file to activate it.
  7. Save and close your custom settings file.
  8. Close the file DefaultModuleSettings.js.
  9. Ensure any page using the Onboarding module, such as the Results page, has a settings file configured to load your custom settings file.
Copy 
/* uncomment next section to configure Onboarding */
/* 
SH.Onboarding = SH.Onboarding || {};
SH.Onboarding.CustomSettings = {};
SH.Onboarding.PathsToExclude = [];