# Adopt advanced use cases This page provides additional tips and guidance to help you navigate edge cases within Adopt. It covers advanced concepts, configuration options and other information you may find useful depending on your organizational needs. ## Configuring multiple tenants in the Nexthink browser extension {% hint style="warning" %} These configuration options apply only to organizations with two or more Nexthink Infinity tenants where Nexthink Adopt is activated, and they are available only to [administrators](https://docs.nexthink.com/platform/user-guide/administration/account-management/roles#roles-administration). {% endhint %} You can integrate the Nexthink browser extension with multiple Nexthink tenants. This allows you to develop guide content associated with different Nexthink environments using Adopt Editor. This capability is useful, for example, when you need to create Adopt guides for the same web application and link them to different Nexthink environments, ensuring they do not interfere or overlap. This page contains the steps to configure and switch between multiple tenants from the [Nexthink browser extension](https://docs.nexthink.com/platform/getting-started/planning-your-installation/installing-the-nexthink-browser-extension) and open tenant-specific guide content in Adopt Editor. To configure a new tenant for the Nexthink browser extension: 1. Open your browser—Google Chrome or Microsoft Edge—select the *Extensions* icon from the browser toolbar, and locate **Nexthink.** 2. Click the pin icon to add the extension to your browser toolbar. 3. Right-click on the pinned extension (the Nexthink icon) and select **Tenants Configuration.** This will open the extension configuration page, where you should see the default tenant.

4. Click on **Add tenant** and fill in the **Name** and **URL** fields from the **Add tenant** pop-up. * Add the URL of your Nexthink instance. For example: `https://nexthink.tet.nexthink.saas` * The URL cannot include a `/` slash at the end of the URL—also known as trailing slash.

5. Open the action menu for the new tenant and select **Authenticate**. This opens the authentication page in a new window. Once the authentication is complete, you can select this tenant and open associated guides in Adopt Editor.

### Switching tenants to open instance-specific guides in Adopt Editor #### Authenticating to a Nexthink tenant To access guides associated with a particular Nexthink Infinity environment in Adopt Editor you must first authenticate to that Nexthink environment. * Access the **Tenants Configuration** page in the Nexthink browser extension and select **Authenticate** from the action menu**.** * Alternatively, to authenticate to the default Nexthink tenant, right-click on the Nexthink icon on the browser toolbar and select **Sign in as admin**. #### Switching tenants in Adopt Editor 1. Once authenticated, click on the Nexthink icon from the browser toolbar. 2. From the drop-down menu, choose the **Tenant** of interest, and select the target web **Application**. 3. Click the guide of interest to open **Adopt Editor** directly on the web application URL. * The Nexthink browser extension lists only those guides that were created in the associated Nexthink Infinity environment and have not been published. * Refer to the [guide-content-development-from-in-app-adopt-editor](https://docs.nexthink.com/platform/user-guide/adopt/guide-content-development-from-in-app-adopt-editor "mention") documentation for more information on creating and editing guide content.

### Selecting the default tenant In a multi-tenant architecture, to view guides associated with a specific environment as they appear in the web application (e.g., for testing purposes), you must set that tenant as the default. To do this: 1. Go to the **Tenants Configuration** page in the Nexthink browser extension. 2. Open the action menu for the desired tenant. 3. Select **Set as default**. In standard cases, organizations operate under a single Nexthink instance. However, if your organization uses development environments, you may need multiple tenants to test adoption guides in separate environments. ## Adopt NQL capabilities Certain adoption guide events can be queried via [investigation](https://docs.nexthink.com/platform/user-guide/investigations) for the purposes of data collection, measuring guide engagement or analytics. ### Adopt-specific NQL tables {% hint style="info" %} Refer to the [NQL data model](https://docs.nexthink.com/platform/user-guide/nexthink-query-language-nql/nql-data-model) for more details about the Adopt-specific tables. {% endhint %} Adopt mainly uses the following NQL tables: * [`application.guide`](#guide-table-fields): This table represents the guide object, which is any type of guidance provided to end-users, such as walkthroughs, tooltips, or media documents. * [`application.guide_step`](#guide_step-table-fields): This table represents an individual-step object within a Walkthrough-type guide. * [`web.context_help_executions`](#context_help_executions-table-fields): This table tracks employee interactions with Context Help elements from the web application (e.g., clicking the question mark icon, searching guides). * [`web.guide_executions`](#guide_executions-table-fields): This table records the execution event of a guide, which can occur multiple times for each employee using the target web application. * [`web.guide_step_executions`](#guide_step_executions-table-fields): This table captures employee interactions with individual steps within a guide. These tables track user interactions with guides, steps within guides, and Context help executions. The data can be leveraged to understand employee behavior and guide engagement within Nexthink Adopt. These metrics offer the following benefits: * **Querying guide engagement**: Use the new fields to track guide targeting, engagement, execution duration, and other user interaction metrics. * **Increasing guide-related data granularity**: By adjusting the data granularity, you can gain precise insights into how employees interact with guides, such as the exact timing of when an end-user engages with specific steps or elements. ### Adopt-related configuration objects in the `application` NQL namespace #### `guide` table fields The example below uses `nql_id`field object from the `guide` table of the `application` NQL namespace. ``` application.guides | list nql_id ```

Field Name	Description
`nql_id`	Unique identifier for the guide.
`name`	Unique identifier for the guide.
`type`	Type of guide (e.g., Walkthrough, Tooltip, Media).
`status`	Status of the guide (e.g., Published, Draft).

#### `guide_step` table fields The example below uses `rank`field object from the `guide_step` table of the `application` NQL namespace. ``` application.guide_steps | sort rank asc | limit 10 ```

guide_step table field	Description
`nql_id`	Unique identifier for the guide step.
`name`	Name of the guide step.
`type`	Type of step (e.g., Walkthrough Step, Action, Decision).
`rank`	Position or sequence of the step in the guide.
`guide_nql_id`	Relation to the guide identifier containing this step.

### Adopt-related events in the `web` NQL namespace #### `context_help_executions` table fields The example below uses `browser_language`field event from the `context_help_executions` table of the `web` NQL namespace. ``` web.context_help_executions during past 24h | sort browser_language desc ```

context_help_executions table field	Description
`execution_id`	Unique identifier for the Context Help execution.
`status`	Status of the Context Help execution: open, closed.
`url`	The URL where the interaction occurred.
`duration`	Duration the Context Help remained open.
`browser_language`	Language of the user's browser fro Context Help executions.
`number_of_executions`	Used for calculating aggregated metrics in NQL (always 1 for each event).

#### `guide_executions` table fields The example below uses `status`field event from the `guide_executions` table of the `web` NQL namespace. ``` web.guide_executions from 2025-02-03 11:00:00 to Feb 4, 2025, 11 AM | list status ```

guide_executions table field	Description
`execution_id`	Unique identifier for the guide execution.
`status`	Status of the guide execution. targeted: The guide was targeted to the user (the guide was made available to the user). started: The guide execution began, and the user interacted with it. completed: The guide execution was completed by the user. closed: The guide was closed by the user before completing or completing its steps.
`number_of_executions`	Used for calculating aggregated metrics in NQL. The value for every event is always 1.
`duration`	Duration the guide was visible to the end-user.
`browser_language`	Language of the user's browser for guide executions.
`targeting_count`	Count of how many times the guide was targeted to specific user/key page/day.
`url`	URL where the guide was triggered.
`time`	Timestamp when the guide execution occurred.

#### `guide_step_executions` table fields The example below uses `number_of_executions`field event from the `guide_step_executions` table of the `web` NQL namespace. ``` web.guide_step_executions on 2025-02-04 | list number_of_executions | limit 100 ```

guide_step_executions table field	Description
`execution_id`	Unique identifier for the guide step execution.
`status`	Status of the guide step: completed: The step was completed (the user finished interacting with that step). closed: The step was closed, typically when the user closes or abandons it before completion.
`url`	URL where the guide step was executed.
`duration`	Duration the guide step was visible to the end-user.
`number_of_executions`	Used for calculating aggregated metrics (like count) in NQL. The value for every event is always 1.
`engaged`	Identifies whether the user engaged with the guide step (true/false).
`browser_language`	Language of the user's browser for guide step executions.
`time`	Timestamp when the guide step was executed.

## Adopt Editor use cases The following use cases apply to the Adopt Editor. Apply them to configure and manage guides in a sustainable way. ### Hidden steps Hidden steps are used to perform actions or wait for user interactions without displaying any overlay to the user. They handle background logic within a guide, such as navigating to a specific page, waiting for a page to load, scrolling to an element, showing a border around an element, or pausing until a user interaction occurs. To add a hidden step: 1. Add a new step and label it appropriately without adding content. 2. Open the step configuration. In **Appearance**, set **Step overlay** to **Hidden**. This ensures the user will not see an empty overlay. Set **Shadow** to **Off** to prevent brief visual flickers. 3. Configure the step as necessary. The following use cases utilize hidden steps, providing insight into their utility.

3. Save your settings. ### Using a ripple effect to highlight specific elements Use a ripple effect to visually highlight points where user interaction is required for guides directly on the page, rather than relying on the user to find the specific element. 1. Create or open a guide in the Adopt Editor that should start from a specific element on the page. 2. Add a step positioned near or tied to the target element. 3. Open the step configuration. In **Triggers**, configure the start trigger for the step under **Step is started when** (for example, click or hover on the element). * You can also use **Step is completed when** for the trigger. 4. Click the configuration button near the selection drop-down. Under **Appearance**, select the **Ripple** effect.

5. Save your settings. 6. When previewing the guide, the target element should now display a blinking ripple effect.

### Triggering steps when hovering a button Validate step conditions by triggering a step when the user hovers over a specific element, such as a button. This approach helps confirm that required fields or conditions are met before the user continues, ensuring that each action occurs at the right time. 1. Open the guide in the Adopt editor. 2. Add a **new step** for detecting the hover action. * You can make this a hidden step. If you do, you must set the **Step is completed when** trigger to **complete step immediately**. 3. Use the selector tool to capture the target element. 4. Open the step configuration. In **Triggers**, set **Step is started when** to **Mouse over**.

5. In **Appearance**, set **Step overlay** to **Hidden.** Set **Shadow** to **Off.**

6. Once the hover event is detected, the step completes automatically and the guide continues to the next visible step. 7. Save and test to confirm that the step waits correctly until the user hovers over the element, then proceeds as expected. ### Automatically completing steps after elapsed time without user interaction Use step automation to streamline your guide and reduce unnecessary clicks. This can be achieved through timers and actions, allowing the guide to progress independently and reducing manual interaction for the end user. 1. Open the guide in the Adopt Editor. 2. Select the step that interacts with the intended element. 3. Open the step configuration. In **Triggers**, under **Step is completed when**, set a timer to automatically end the step after a few seconds (for example, 3 seconds). * Keep the **Action type** set to **Mouse click** for redundancy so the user can still advance the guide manually.

4. Save your settings. 5. Publish and test the guide to confirm that steps complete automatically and clicks occur in the correct order. ### Allowing a single value for field validation Trigger field validation when a user interacts with an input field, and show guidance immediately if the value does not match a required pattern. 1. Open the guide in the Adopt Editor. 2. Create a step intended for the field input. 3. Open the step configuration. Under **Triggers**, set **Step is started when** to **Mouse click** and **Step is completed when** to **Fill/select value and move off**. 4. Configure **Fill/select value and move off** with an appropriate [Regular expression pattern](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions/Cheatsheet) that fits your needs. The step cannot be completed unless the value matches the one you defined. Invalid user input results in an error message. * In this use case, a single word phrase does not require any additional syntax, but a combination of multiple words can be achieved with `(EXAMPLE1|EXAMPLE2)` or a substring with `.*EXAMPLE.*`. 5. Save the configuration and test your guide.

### Triggering warning messages on incorrect value input Trigger a validation message only if the user inputs an incorrect value. Use this method to monitor multiple fields with separate validation logic. 1. Open the guide in the Adopt Editor. 2. Create a hidden step intended for validation. 3. Open the step configuration. Under **Appearance**, set **Step overlay** to **Hidden**. Under **Triggers**, set **Step is completed when** to **Fill/select value and move off**. 4. Configure **Fill/select value and move off** with a specific inverted logic pattern such as `^(?!EXAMPLE$).*`. The step triggers when the field input matches anything except the phrase embedded in the pattern. 5. Save the configuration. 6. Create a step and edit the content to a message that states anything except your desired input is not allowed. 7. Optionally, create a decision after this message and configure it so that the error message step loops back to the user input step until the correct input is provided. 8. Save the configuration and test your guide.

### Automatically completing steps based on specific inputs Complete a step automatically when the user selects a specific value or option (for example, a particular status in a dropdown). This removes the need for the user to click **Next** after choosing the correct value. 1. Open the guide in the Adopt Editor. 2. Select the step that should be completed when the user selects a specific value or option. 3. Open the step configuration. Add a **validation / completion rule** based on the selected value (for example, when status equals *New*). 4. Configure the rule so that: * If the user selects the correct value, the step is marked complete and the guide moves to the next step automatically. * If the user selects another value, the step stays active and the user must click **Next** manually (or correct the selection). 5. Save and test by selecting both correct and incorrect values to confirm the behavior. ### Language-dependent selectors Ensure guide reliability across different interface languages by choosing selectors that are not affected by localized text. XPath selectors contain language-specific text values that can change when the UI is translated, which may cause steps to fail. CSS selectors are generally more stable and language-independent. As a general rule, ensure that steps which utilize XPaths are multilingual to increase overall stability. 1. Open the guide in the Adopt Editor. 2. Select the step that is causing language-related instabilities. 3. Open the step properties. In **Position**, review the **Selector** field: * If the selector uses **XPath** and references text (for example, button labels), it will only work in that language. 4. To support multiple languages, use one of the following options: * **Option 1:** Reselect the element for each language version so that each locale has its own XPath. * You can switch languages through the toolbar or in the step configuration. * If not localized, the XPath for a specific language will be empty. * **Option 2:** Use a **CSS selector** (instead of XPath selector) that targets structural or class-based attributes instead of text. 5. Use broad and stable selectors when possible. The best practice is to avoid dynamic IDs or any elements that change as a page loads. 6. Test the guide in each supported language to ensure all elements are correctly detected and the steps trigger as expected. *** RELATED TOPICS * [configuring-adoption-settings](https://docs.nexthink.com/platform/user-guide/adopt/guide-creation-and-management-from-nexthink-applications/configuring-adoption-settings "mention") * [guide-insights-and-analytics](https://docs.nexthink.com/platform/user-guide/adopt/guide-insights-and-analytics "mention")