# Configuring Shadow DOM Selectors

[Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM) is a technique within SaaS applications that enables developers to attach a DOM tree to web elements in HTML, with its internals hidden from JavaScript and CSS running on the page. 

Nexthink offers a set of selectors that facilitate detecting these elements and delivering DAP content to them. In some instances, customizing a selector ensures better detection accuracy.

## Shadow DOM areas within SAP SuccessFactors

Below are some specific examples that Nexthink has identified and provided configuration for.

{% hint style="info" %}
Employees see the items in this list differently based on the user role and the current URL.
{% endhint %}

### Menu Button

Although the text of this button is different across pages, the required attribute data is consistent.\
Nexthink Adopt's System page targeting ensures the configuration only shows on the correct pages.

<figure><img src="/files/bqyQPnMjYS82bxpZknQQ" alt=""><figcaption><p> </p></figcaption></figure>

#### Configuration

1. Open the Adopt Editor from within the application.
2. Choose `Create step` and select the required element.
3. Within the Step Editor, click the `Position` tab.
4. Navigate to the `Element JSPath` selector.
5. Replace the existing element JSPath within the data below:

`[data-ui5-stable='sf-header-shellbar'],ui5-shellbar-sf-header#shellbar[data-ui5-stable='shellbar'],* *[data-ui5-stable='menu']`

### Menu Dropdown list

Several items are available when a user selects the Menu as shown in the image below. This area is contained within shadow DOM trees.

<figure><img src="/files/eAPxnO6NJtXvC8zuHmAw" alt="Example of Shadow DOM elements within the Menu drop-down list"><figcaption></figcaption></figure>

#### Configuration

To add a stable selector for any item within this list:

1. Open the Step Editor.
2. Create/edit a step and select the menu item element.
3. Navigate to the `Position` tab.
4. View the current `Element JSPath` selection.
5. Identify the module associated with the selection by searching for `[data-ui5-stable='Module-` within the text area.\
   For example, `[data-ui5-stable*="Module-TALENTREVIEW"]`is contained in the following image.

<figure><img src="/files/yS1xxpUDroQ6ZjOZhrBh" alt=""><figcaption></figcaption></figure>

6. Append the identified module data with the following:\
   `ui5-static-area-item-sf-header,* *`
7. The result should look like this:\
   `ui5-static-area-item-sf-header,* *[data-ui5-stable*="Module-TALENTREVIEW"]`

If you use the click trigger for step completion, add the following Element JSPath selector into that area.

<figure><img src="/files/E4ATGTOAy11ccJQRyyDF" alt="Preview the selection to make sure it is correct before saving the step"><figcaption></figcaption></figure>

#### Example selectors

The table below showcases the custom Element JSPath selectors required for the configured menu item:

| Item             | Element                                                                       |
| ---------------- | ----------------------------------------------------------------------------- |
| Home             | `ui5-static-area-item-sf-header,* *[data-ui5-stable*="Module-HOME"]`          |
| Admin Center     | `ui5-static-area-item-sf-header,* *[data-ui5-stable*="Module-ADMIN"]`         |
| Calibration      | `ui5-static-area-item-sf-header,* *[data-ui5-stable*="Module-CALIBRATION"]`   |
| Company Info     | `ui5-static-area-item-sf-header,* *[data-ui5-stable*="Module-COMPANY_INFO"]`  |
| Compensation     | `ui5-static-area-item-sf-header,* *[data-ui5-stable*="Module-COMPENSATION"]`  |
| My Employee File | `ui5-static-area-item-sf-header,* *[data-ui5-stable*="Module-EMPLOYEE_FILE"]` |
| Objectives       | `ui5-static-area-item-sf-header,* *[data-ui5-stable*="Module-GOAL"]`          |
| Performance      | `ui5-static-area-item-sf-header,* *[data-ui5-stable*="Module-PERFORMANCE"]`   |
| Presentations    | `ui5-static-area-item-sf-header,* *[data-ui5-stable*="Module-TALENTREVIEW"]`  |
| Recruiting       | `ui5-static-area-item-sf-header,* *[data-ui5-stable*="Module-RECRUITING"]`    |
| Reporting        | `ui5-static-area-item-sf-header,* *[data-ui5-stable*="Module-REPORT"]`        |
| Succession       | `ui5-static-area-item-sf-header,* *[data-ui5-stable*="Module-SUCCESSION"]`    |

### Menu tabs

Most areas of the system have a series of tabs available within the top menu section (highlighted below).\
All available tabs are within shadow DOM trees. Nexthink recommends configuring a custom Element JSPath for these areas.

<figure><img src="/files/paRuFc28fUWspCdjCvme" alt="Example of Shadow DOM within Menu tabs on the Job Requisitions page"><figcaption></figcaption></figure>

#### Configuration

To add a stable selector for any item within this list:

1. Open the Step Editor.
2. Create/edit a step and select the menu item element.
3. Navigate to the `Position` tab.
4. View the current `Element JSPath` selection.
5. Identify the module associated with the selection by searching for `[data-ui5-stable='bizxSubTab` within the text area.\
   For example, *`[data-ui5-stable='bizxSubTab_RECRUITING_EMAIL_CORRESPONDENCE_MESSAGE_CENTER'`*`]`is contained in the following image.

<figure><img src="/files/2ij8fcvz7sp25bur5He6" alt=""><figcaption></figcaption></figure>

6. Append the identified module data with the following:\
   `[data-ui5-stable='sf-header-shellbar'],ui5-tabcontainer-sf-header,* *`
7. The result should look like this:\
   `[data-ui5-stable='sf-header-shellbar'],ui5-tabcontainer-sf-header,* *[data-ui5-stable='bizxSubTab_RECRUITING_EMAIL_CORRESPONDENCE_MESSAGE_CENTER']`

If you use the click trigger for step completion, add the following Element JSPath selector into that area.

#### Example selectors

The table below showcases the custom Element JSPath selectors required for the configured elements:

| Item                       | <p><br></p>                                                                                                              |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Org Chart                  | `[data-ui5-stable='sf-header-shellbar'],ui5-tabcontainer-sf-header,* *[data-ui5-stable='bizxSubTab_COMPANY_ORG_CHART']`  |
| Position Org Chart         | `[data-ui5-stable='sf-header-shellbar'],ui5-tabcontainer-sf-header,* *[data-ui5-stable='bizxSubTab_POSITION_ORG_CHART']` |
| Company Structure Overview | `[data-ui5-stable='sf-header-shellbar'],ui5-tabcontainer-sf-header,* *[data-ui5-stable='bizxSubTab_ENTITY_ORG_CHART']`   |
| Directory                  | `[data-ui5-stable='sf-header-shellbar'],ui5-tabcontainer-sf-header,* *[data-ui5-stable='bizxSubTab_COMPANY_DIR']`        |

## Customizing a Selector System <a href="#successfactors-customisingaelementjspathselectorforshadowdomelements-workaround" id="successfactors-customisingaelementjspathselectorforshadowdomelements-workaround"></a>

The following sections describe the process of customizing a selector using the Management Console and Step Editor, focusing on SAP SuccessFactors. Note that this can also apply to any application using Shadow DOM.

### Identifying if an element uses Shadow DOM

Follow the steps below to confirm if web elements are contained within Shadow DOM.

1. Launch Developer Tools (F12 within Web Browser).
2. Click the <img src="/files/fuaZQbudZmq1yFUBeOKY" alt="" data-size="line"> 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.

<figure><img src="/files/XqdR3WPVCMwLDloh3dis" alt="How to identify elements contained within Shadow Root "><figcaption></figcaption></figure>

### Identifying stable element data

Adopt attempts to determine which element data is best suited for element detection. In some use cases, however, you may be required to create specific custom attributes to ensure the guidance works as expected for your users.  You can use the Developer Tools option within your Web Browser by inspecting the web element data to identify a stable identifier.&#x20;

In this example, you can add the recommended `data-ui5-stable` attribute to the application through the `Space` settings menu within the Management Console.

<figure><img src="/files/S7rdnQmNIzWlvY4K5iM2" alt=""><figcaption></figcaption></figure>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs-adopt.nexthink.com/in-application-guidance/using-element-selector/advanced-element-selector-techniques/configuring-shadow-dom-selectors.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.