How to Configure the Onboarding Module
About
The Onboarding module enables SmartHub to interact with users the first time they visit the SmartHub site.
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
How to Customize the Onboarding Module
Before continuing, familiarize yourself with the information in the topic How to Use the UI Builder. Note that the Onboarding module is disabled by default.
UI Builder
-
The easiest and fastest way to insert and customize Onboarding is via the SmartHub UI Builder.
-
For more information, see How to Use the UI Builder.
-
SmartHub administrators can simply click the UI Editor link from the SmartHub Administration page.
-
Click the Select a page link from the top menu.
-
Select (double-click) an HTML page such as Results.html page.
-
Below, the Results.html page is shown for sample purposes.
-
BA Insight recommends you use page and folder to modify. Leave the default files as templates.
-
Example: Customizations/CustomResults.html. Default Results.html is under the top most SmartHub directory.
-
-
-
Select the Advanced mode from the top right of the page.
-
Select Advanced settings edit.
-
Scroll down to line 310 (this may vary), which contains the text
SH.Onboarding.CustomSettings
-
Click the link Default Settings at the top right.
-
A new browser tab opens with all available SmartHub module settings.
- Search for the word "Onboarding" on the page to quickly navigate to the Onboarding default settings, shown below:
- Copy the Onboarding settings section from SH.Onboarding.DefaultSettings.
- Go back to your Advanced settings edit tab.
- Paste the copied settings inside section SH.Onboarding.CustomSettings.
Note: By default, Onboarding is disabled by default:
Enabled: false.
-
Modify settings as desired. Refer to the "Onboarding Settings" table below.
-
Click Save changes.
-
Click the link Preview <html> file.html at the top of the code editor.
-
Review your HTML page in the new tab that opens.
-
Make any necessary changes back in the code editor. Repeat steps 14-18 as necessary.
-
Click Save changes.
SH.Onboarding = SH.Onboarding || {};
SH.Onboarding.DefaultSettings = {
Enabled: false,
GenericDialogTemplatePath: SH.RootLevelURL + "/modules/Onboarding/templates/GenericDialogTemplate.html",
OnboardingModules: {
"FederatedImpersonation": {
Active: true,
Priority: 1,
Path: SH.RootLevelURL + "/modules/Onboarding/OnboardingModules/FederatedImpersonationModule.js",
ModuleSettings: {
Backends: {
"iManage": {
TrySilentAuth: true,
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",
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!"
},
"OtherBackendRequiringLogIn": {
TrySilentAuth: true,
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!"
}
}
}
},
"SampleOnboardingModule": {
Active: false,
Priority: 2,
Path: SH.RootLevelURL + "/modules/Onboarding/OnboardingModules/SampleOnboardingModule.js",
ModuleSettings: {
CustomSettingName: "CustomSettingValue"
}
}
}
}Onboarding Settings
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:
|
| OnboardingModules |
Object Default: Copy
|
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 this is set to true, the Federated Impersonation sub-module checks the results on the page for an "authorization required" result for a specific search engine (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.
|
||||||
|
Path |
String Default: SH.RootLevelURL + |
The path to the file which contains the implementation of the sub-module.
|
||||||
|
ModuleSettings |
Object Default: Copy
|
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 (search engines) that require authentication:
|