Configuring Adoption settings

Adoption settings are only accessible to users with an administrator role.

Refer to the Deploying a guide: end-to-end procedure for a summarized sequence of steps for publishing a guide.

Adoption Settings allow you to set default behaviors for all guides within a web application. This includes element selectors and guide component setups that shape content development in Adopt Editor. In addition, you can also select default options for displaying Context help.

Adoption settings include the following subtabs:

• Settings subtab

• Localization subtab

• Theme subtab

• Context help subtab

Configuring Adoption Settings for the selected application

From Nexthink Applications > Manage applications, select a web application with guides. Open the Adoption settings tab > Settings subtab to:

1. Enable or disable Guide defaults for guide-component behaviors.

2. Determine how Adopt Editor captures page elements directly from the web application based on a pre-defined set of instructions for element selectors.

3. Save settings.

Setting Guide defaults

Configure the following default behaviors for your guide components:

• Navigate to URL address when step is shown: Automatically navigate to a configured URL when the employee reaches a specific step or component in the guide.

• Ignore key page selection: Enables a guide step or component to become visible every time a specific element is present in the application page view, regardless of the webpage.

  • This means the system ignores the key page and relies solely on the element selector to display the guide step attached to it.

• Scroll to view element: Enables automatic page scrolling to the step-specific element when the user reaches the relevant step.

• Display step when element is not covered: Enables a guide step to be visible only when not covered by an additional layer, such as a modal dialogue. If unselected, it allows the step to be visible despite additional layers.

• Persist step after completion: Enables a guide step to remain after the user completes it.

  • Any: The setting works regardless of user interaction with the step.

  • On reload: The setting works on page reload.

  • On navigate: The setting works when the user changes URL.

  • On back forward: The setting works when the user returns to a previous page.

You may customize the Guide defaults when configuring the Position property tab of a specific guide overlay (step, action, tooltip, etc.) from Adopt Editor directly on the web application—regardless of the guide type.

The Ignore recorded query parameters, Enable position recalculation when user scrolls and Scrolling container locations features are scheduled for deprecation as Nexthink Adopt is improved.

Defining a Selectors framework

Determine Element selectors and Selector overrides to specify default instructions on how Adopt Editor captures page elements directly from the web application. These instructions define the Selectors system that Adopt uses to interpret the internal rendering structure.

Nexthink assists you in fine-tuning element selection by:

• Identifying multiple types of selectors to increase the chance of finding the element.

• Detecting dynamically generated identifiers and stripping them of dynamic components to render them more reliable for the process.

You may customize the Selectors settings when configuring the Position property tab of a specific guide overlay (step, action, tooltip, etc.) from Adopt Editor directly on the web application—regardless of the guide type.

Defining Element selectors

The following Element selectors fields require familiarity with Identifying and extracting attributes from web pages, such as element IDs.

Fill in the following Element selector fields to avoid visual errors when capturing elements in Adopt Editor. However, this is case-by-case, as some websites have a more complex design than others.

Updating the Elements selectors fields after saving settings only affects the element selections made afterward; it does not update element selectors within existing guide components already configured in Adopt Editor.

Selector 'class only' field

Some pages include dynamic elements that are unreliable for guides. This setting lets you specify an element and strip it of its dynamic component, making it more reliable.

• Pattern: Define a class that includes dynamic elements by replacing those elements with a wildcard. For instance, table-layout-1234-top would be input as table-layout-*-top.

• Replacer: Define the same class as above but without any dynamic elements. Following the same example, input table-layout-top.

In either field, you can include several elements separated by a comma.

Ignored element IDs field

Element IDs are the most common way of addressing page elements. However, this does not always apply, as element visibility can depend on user and page states.

This setting allows you to ignore elements that may not always be present when recording steps. You can include several elements separated by a comma.

Ignored element class names field

Class names can be used by multiple HTML elements, and they are often employed in visual styles that result in different page state representations.

This setting allows you to ignore the outcome of these different states, as they can interfere with guide steps. You can include several elements separated by a comma.

Included element custom attribute names field

If you are working with dynamic class names, removing the dynamic component may cause issues in page state representations. This setting allows you to use any custom attributes present in the div when the element is recorded in a guide step. You can include several elements separated by a comma.

Example for Workday web application page elements:

data-automation-id, data-uxi-widget-type

Example for SAP SuccessFactors web application page element using Shadow DOM:

data-ui5-stable

Enabling/disabling Element selector overrides

Updating the Elements selector overrides only affects the element selections made afterward; it does not update element selector overrides within existing guide components already configured in Adopt Editor.

These options allow you to define which selectors the system enables by default for specific applications.

• Element XPath: Selectors based on language-specific element text values.

• Element CSS path relative: Relative CSS selectors consisting of a tag name, className, ID and nthChild. Between every element selector, there is a > combinator.

  • If a parent has an ID attribute, the CSS selector will start from that element instead of the body.

  • For example: div#target.element:nthChild(0)

• XPath element - limited: Same as the CSS path relative selector, but converted to an XPath expression.

• Element CSS path relative limited (without nth-child selector): Same as the CSS path relative selector, but without an nthChild() pseudo-class.

• Element CSS expressed path: Selectors only with a class name, but the target element is expressed using relative selectors: .class1 .class2 > div#target.element:nthChild(0).

• Element CSS class-only path: Selectors created only with a class name.

• Element CSS tag-only path: Selectors created only with a tag and nthChild pseudo-classes joined with a > combinator.

Identifying and extracting attributes from web pages

To define element selectors under the Settings tab, you must first identify and extract the attributes directly from the webpage.

From your browser:

1. Launch the developer tools (F12) within MS Edge and Chrome browsers.

   • Alternatively, right-click to Inspect.

2. Click the icon within the Toolbar.
3. Select the required element with the mouse cursor.

4. From the right-side Elements panel, you will see the related data to the selected element.

5. Evaluate if any attributes contain stable data. You should sample 5-6 elements as a comparison.

Alternatively, extract CSS selector from the web application page using your Nexthink browser extension—the extension does not currently support Firefox.

In the image below, the data-automation-id attribute is a candidate for element selector.

For dynamically complex elements encapsulated by a Shadow DOM, such as dropdowns or menus on a webpage, simply extracting attributes may not be sufficient for consistent detection accuracy.

Identifying if a web page element uses Shadow DOM

Shadow DOM is a web development technique that allows you to attach and encapsulate a separate Document Object Model (DOM) tree to HTML elements. This ensures that styles and scripts within the Shadow DOM do not affect the rest of the page.

For real examples of shadow DOM elements, refer to the Use case: Shadow DOM Selectors configuration for SAP application.

Follow the steps below to confirm if web elements are contained within Shadow DOM. For these cases, you should create a custom stable identifier for element selection for detection accuracy.

1. Launch Developer Tools (F12 within Web Browser).

2. Click the icon.
3. Hover over the elements you wish to inspect.

4. Within the right-hand element pane, scroll up from the selected element.

5. Verify if the element is nested within a shadow-root (open) area. See the image below.

---

Configuring the Localization settings for the selected application

Localization uses AI-powered automatic translations to localize guide content based on the employees' browser settings.

To activate AI-generated localization, from Nexthink Applications > Manage applications select a web application with guides. Open the Adoption settings tab > Localization subtab:

• Select up to 5 languages. If the user's language is not among the selected options, the system defaults to English.

After selecting a set of languages in the Localization tab, activate the content translation when creating or configuring a specific guide—as translation is activated at the guide level.

---

Customizing the Adopt Theme for the selected application

The Theme subtab details the Adopt default color scheme to display guide components (steps, actions, tooltips, etc.). These default colors are sensitive to the employee's browser display configuration: dark theme or light theme.

To customize the Adopt color scheme and appearance for a specific application, from Nexthink Applications > Manage applications, select the web application with guides. Open the Adoption settings tab > Theme subtab:

1. Determine the custom color scheme—using HEX color nomenclature, for example: #1046a8.

2. Fill in the Background color, Primary color and Accent color with the Custom colors.

The HEX color convention specifies colors using six hexadecimal (base-16) digits. These digits are grouped in pairs (RR, GG, BB) to represent the intensity of red, green, and blue from 00 to FF.

---

Configuring Context help settings for the selected application

The Context help feature, accessible via a question mark icon in the web application, allows employees to search for context-specific guides or documents for self-help.

Configure how the Context help pop-up appears and behaves on the target application site by default.

From Nexthink Applications > Manage applications, select a web application with guides. Open the Adoption settings tab > Context help subtab:

1. Choose a launcher position.

2. Edit placeholders.

3. Optionally, suppress visible tours.

4. Optionally, enable guidance control.

5. Optionally, customize composition.

6. Save settings.

Launcher position

From the Launcher position drop-down, select a position for the Context help launcher (the exclamation-point icon):

• The Theme positioned option follows a CSS definition predetermined by Nexthink when placing the launcher.

• The Attached to element option embeds the launcher into an existing page element. Therefore, you should paste the CSS selector of the element in question. For example: div.data-uxi-widget-type["value"]

Placeholders

Fill in the fields Search placeholder and No results placeholder to change the default text displayed in the Context help pop-up when searching content:

• Search placeholder: changes the default text displayed within the search field in the Context help pop-up. For example, Write the guide name here.

• No results placeholder: changes the default text displayed in the Context help pop-up after finalizing a failed search. For example, No matches have been found.

Suppress visible tours

You can suppress visible tours when an employee starts a new guide from the Context help pop-up. This configuration avoids having two guides displayed simultaneously.

Enable guidance control

Enable guidance control to activate the Guidance on/off toggle button for employees following a guided tour within the application site. Display the Guidance on/off toggle from these places:

• Context help: within the Context help pop-up.

• Launcher: above the Launcher (the exclamation-point icon).

• Step: within a Step pop-up of the guided tour in question.

• Context help and Step or Launcher and Step: within combined display locations aforementioned.

• Everywhere: all of the options above.

Optionally, fill in the fields Label for guidance turned on and Label for guidance turned off to change the text displayed in the toggle button.

Composition

Change the section headings—displayed in the Context help pop-up—that categorize Walkthroughs and Media-type guides. Replace the default headers with specific labels.