# Product configuration

The Product configuration page lets you enable specific features and determine how the system classifies devices and users in your Nexthink tenant.

## Features

Change the enablement status of certain features in your Nexthink tenant in the **Configuration** subtab.

* **AI Tools:** Enable the use of AI tools, enabling you to:
  * Uncover AI usage in your organization, including unapproved or shadow tools.
  * Track adoption patterns, highlighting champions and areas of friction.
  * Benchmark AI adoption against peers to stay competitive.
  * Quantify impact through perceived time saved and employee feedback.
  * Scale what works by acting on AI adoption insights with recommendations.
    * Refer to [getting-started-with-ai-tools](https://docs.nexthink.com/platform/user-guide/ai-tools/getting-started-with-ai-tools "mention") for more information.
* **Web search:** Enable Workspace to retrieve information from a curated set of external sources, helping you answer questions that require up-to-date vendor guidance, known issues, or industry best practices.
  * Refer to [#web-search](https://docs.nexthink.com/platform/search-and-workspace/using-workspace#web-search "mention")for more information.

<figure><img src="https://268444917-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxJSUDk9NTtCHYPG5EWs3%2Fuploads%2FRS9wCLkNoxcPyRMsp39v%2Fimage.png?alt=media&#x26;token=b6f77bb2-f11f-4f56-a9db-717d67ff63dc" alt=""><figcaption></figcaption></figure>

## Device and user classification

The **Device and user classification** tab in **Product configuration** lets you determine how the system classifies devices and users in your Nexthink tenant.

Use device and user classifications across Nexthink products and features to:

* Leverage NQL data model tables—`device.organization, device.location, user.organization`—to query data and run investigations.
* Define filters and breakdown criteria for sorting built-in dashboards and specific custom visualizations. Refer to [Configuring AI tools](https://docs.nexthink.com/platform/ai-tools/configuring-ai-tools#configuring-custom-filters-for-ai-tools-dashboards) documentation for a use case example of custom filters.

The system provides three main classification configurations:

* **Device location** uses a rule-based logic and/or GeoIP based on public IP—the system uses GeoIP as a fallback. Device location enables you to know where a device is at the time of an event, enabling effective issue troubleshooting and consistent support. Device locations are expected to change frequently.
* **Device organization** uses a custom ruleset to map devices with organizational entities, enabling you to manage access, compliance, and hardware lifecycle by organization structures or branches (for example, the US branch, Swiss office, etc.). Unlike Device location, Device organization is fairly stable over time.
* **User organization** uses up to six levels, from top-level to lowest, to define organization hierarchies and map them to your employees—matching data from your HR management tool.

{% hint style="warning" %}
Accessing **Administration** > **Product configuration** > **Device and user classification** requires administrator [permissions](https://docs.nexthink.com/platform/user-guide/administration/account-management/roles).
{% endhint %}

<figure><img src="https://268444917-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxJSUDk9NTtCHYPG5EWs3%2Fuploads%2Fgit-blob-8c47a271ae804326899cf24f1204b94498dcf1c1%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

***

## Configuring Device location

**Device location** enables you to know where a device is at the time of an event, helping you troubleshoot remote issues and ensure a consistent digital experience (DEX). Events are tracked by geographical location and location type: onsite or remote.

Nexthink determines location using rule-based logic—preferred for accuracy—or GeoIP based on public IP, used as a fallback when unable to assign rule-based location. Device locations are expected to change frequently.

From the **Administration** > **Product configuration** > **Device and user classification** tab, under **Device location**:

1. Set **Geolocation granularity**
2. Define **Rule-based location**

### Setting Geolocation granularity <a href="#productconfiguration-geolocationtab" id="productconfiguration-geolocationtab"></a>

Nexthink can determine the location of devices on the internet by referencing the GeoIP database and public IP addresses of the systems running Collector.

The geolocation feature is disabled by default ("Do not capture any location data"), but you can enable it by setting the location granularity to one of the options available in the drop-down menu.

* Do not capture any location data
* Public IP only
* Public IP and country
* Public IP, country, and state
* Public IP, country, state, and city

<figure><img src="https://268444917-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxJSUDk9NTtCHYPG5EWs3%2Fuploads%2Fgit-blob-7c7c09aff40488e1e8114b359ca2fed5a2ec8f3a%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
When you enable the geolocation feature, the Nexthink platform records the name of the Internet service provider (ISP) independently of the selected level of granularity.
{% endhint %}

Using a virtual private network (VPN) affects the public IP address reported by Collector. To improve the geolocation precision, it is best to avoid routing the traffic between Collector and the Nexthink instance through a VPN. The feature works with any version of Collector, and no information is transmitted outside the Nexthink platform. Nexthink has its own instance of the geolocation database and performs the geolocation lookup internally.

### **Defining Rule-based location** <a href="#productconfiguration-locationtypetab" id="productconfiguration-locationtypetab"></a>

The Nexthink platform features a rule-based assignment process that enables the system to determine a device's location. This feature is highly configurable, and you can adjust it by modifying the rules.

Configure the assignment using a CSV file with a tabular structure. Each row in the table contains two patterns and a location assignment.

{% hint style="warning" %}
When using IP address fields with CIDR notation in rule-based location rules, the same CIDR format requirements apply as for device organization rules. Refer to [#classless-inter-domain-routing-cidr-format-requirements-for-ip-based-rules](#classless-inter-domain-routing-cidr-format-requirements-for-ip-based-rules "mention").
{% endhint %}

<figure><img src="https://268444917-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxJSUDk9NTtCHYPG5EWs3%2Fuploads%2Fgit-blob-eba43509cd9fa3789063e45fc060914d48be6d2c%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

### **Example of a CSV file for rule-based location**

Example of the comma-separated, assignment text file:

```
Field1,Pattern1,Field2,Pattern2,Location Type,Site,State,Country
primary_local_ip,10.0.0.0/8,name,NXT*,Onsite,Lausanne,VD,CH
primary_local_ip,172.16.0.0/16,,,Onsite,Boston,MA,US
name,*,,,Remote,,,
```

{% hint style="info" %}
Refer to [Supported values for Field1 and Field2](#supported-values-for-field1-and-field2) on this page for more information.
{% endhint %}

Table showing the assignment rules from the text file above:

<table data-full-width="true"><thead><tr><th>Field1</th><th>Pattern1</th><th>Field2</th><th>Pattern2</th><th>Location Type</th><th>Site</th><th>State</th><th>Country</th></tr></thead><tbody><tr><td>primary_local_ip</td><td>10.0.0.0/8</td><td>name</td><td>NXT*</td><td>Onsite</td><td>Lausanne</td><td>VD</td><td>CH</td></tr><tr><td>primary_local_ip</td><td>172.16.0.0/16</td><td></td><td></td><td>Onsite</td><td>Boston</td><td>MA</td><td>US</td></tr><tr><td>name</td><td>*</td><td></td><td></td><td>Remote</td><td></td><td></td><td></td></tr></tbody></table>

* The first rule tags all devices belonging to the local subnet 10.0.0.0/8 whose name starts with *NXT* as *Onsite* and assigns location site Lausanne.
* The second rule tags all devices belonging to the local subnet 172.16.0.0/16 as *Onsite* and assigns location site Boston.
* The third rule tags all other devices as *Remote*.

To satisfy a rule, a pattern must match the corresponding field. The system establishes rule precedence from the top to the bottom of the table. You can be more specific with the device assignment at the top of the table and more general at the bottom.

* **Field1**: Data for the first field used for the assignment (See [Supported values for Field1 and Field2](#supported-values-for-field1-and-field2) on this page.)
* **Pattern1**: The pattern for the first field
* **Field2**: Data for the second field used for the assignment (See [Supported values for Field1 and Field2](#supported-values-for-field1-and-field2) on this page.)
* **Pattern2**: The pattern for the second field
* **Location Type**: The name of the target location type. The allowed location type values are:
  * Onsite
  * Remote
  * Unknown
* **Site**: A custom name for the site where the device or devices are.
* **State**: The ISO 3166-2 subdivision code where the device or devices are located. Use this field to indicate a state, province, canton, and so on. For example, for Vaud, Switzerland: `VD`
* **Country**: The ISO 3166-1 alpha-2 country code where the device or devices are located. For example, for Switzerland: `CH`

{% hint style="warning" %}
Do not duplicate the **Country** code within **State** field. For example, according to ISO 3166-2, the state field for the Bas-Rhin French Department is `67`, not `FR-67` . In this case, the rule-based location should look like:

`primary_local_ip,55.XXX.XX.X/20, Onsite, Illkirch,`**`67, FR`**
{% endhint %}

#### **Supported values for Field1 and Field2:**

* **name:** The hostname of the device.
* **collector\_tag:** The tag number assigned to Collector during its installation. Only the exact number is matched.
* **collector\_string\_tag:** The label assigned to Collector during its installation. This value supports pattern matching.
* **configuration\_tag:** Configurable label that identifies a group of devices. Set the value of this field using the [Enrichment API](https://docs.nexthink.com/api/enrichment). This value supports pattern matching.
* **dn:** The distinguished name of the device, as reported by Collector. The device must be part of an Active Directory domain. The format of the distinguished name reported by Collector is the standard sequence of `attribute=value` elements connected by commas, from the most specific to the most general attribute. For example:\
  `CN=ex01,OU=Computers,DC=example,DC=org`
* **ad\_site:** The Active Directory site on which the device is located. The **name**, **collector\_string\_tag**, **dn** and **ad\_site** fields support character pattern matching. To define the associated string pattern, use the following wildcards:
  * The `?` character substitutes a single character.
  * The `*` character substitutes zero or more characters.
* **ip:** The last public IP address of the device. This field maps to the `public_ip.ip_address` [NQL field](https://docs.nexthink.com/platform/understanding-key-data-platform-concepts/nql-data-model) in the `devices` table.\
  As a pattern for the field, specify either:
  * A single IP address in dot-decimal notation, for example: `192.168.10.1`
  * A subnet in CIDR notation, for example: `192.168.10.0/24`

{% hint style="warning" %}
Remember, when specifying subnets using CIDR notation, ensure the IP represents the network address of the subnet. Refer to [#classless-inter-domain-routing-cidr-format-requirements-for-ip-based-rules](#classless-inter-domain-routing-cidr-format-requirements-for-ip-based-rules "mention") .
{% endhint %}

* **primary\_local\_ip:** The last local IP of the device for the primary physical network adapter. This field maps to the `connectivity.last_local_ip` [NQL field](https://docs.nexthink.com/platform/understanding-key-data-platform-concepts/nql-data-model) in the `devices` table. Specify patterns in the same way you specified them for the **ip** field.
* **collector\_local\_ip**: The local IP used for the traffic between the endpoint and the Nexthink instance. This field maps to the `collector.local_ip` [NQL field](https://docs.nexthink.com/platform/understanding-key-data-platform-concepts/nql-data-model) in the `devices` table. Specify patterns in the same way you specified them for the **ip** field.
* **wifi\_ssid:** The WiFi network name (SSID) associated with the primary network adapter. This value supports pattern matching.

{% hint style="info" %}
Enable geolocation before starting to build rules based on public IP addresses.

To use the `wifi_ssid` tag, disable the following [Collector parameter](https://docs.nexthink.com/platform/configuring_nexthink/bringing-data-into-your-nexthink-instance/deploying-nexthink-in-non-vdi-environment/installing-collector/windows-collector-references/collector-msi-parameters-reference-table#collectormsiparametersreferencetable-optionalparameters): `ANONYMIZE_WIFI_NETWORK`
{% endhint %}

#### Considerations for CSV file for rule-based location

Ensure that your CSV configuration file meets the following criteria:

* The file size is less than 5MB.
* The file encoding is UTF-8.
* A comma is the field separator.
* Field delimiters are optional and quotes `"` are the only allowed delimiter type.
* The total number of rules or rows is less than 40,000.
* The maximum number of unique sites is 5,000.
* A catch-all rule with `Field1=name` and `Pattern1=*` is entered for the last row of the table.

If any of these checks fail, the file selection will revert to the previously uploaded file. Only when you fix the errors, will you be able to unblock the upload.

{% hint style="info" %}
To prevent programs from automatically adding extra characters when saving, use plain text editors like Notepad++ or Sublime Text to edit your CSV file.
{% endhint %}

***

## Configuring Device organization

{% hint style="warning" %}
Organizations still using classic hierarchies should migrate to **Device organization** custom rulesets.

Refer to the [Entities and Hierarchies to Rule-based Organization](https://edocs.nexthink.com/infinity-transition/detailed-transition-advice/entities-and-hierarchies-to-rule-based-organization) documentation, available to Nexthink Community users, for migration steps.
{% endhint %}

**Device organization** maps devices with organizational entities using an organization ruleset and groups entities in line with organizational structure. This enables you to manage access, support, compliance, and the hardware lifecycle by organization structures or branches (the US branch, the Swiss office, etc.).

Unlike Device location, which changes frequently, Device organization is fairly stable. For example, a Swiss-owned device may be used in multiple countries.

From the **Administration** > **Product configuration** > **Device and user classification** tab, under **Device organization:**

Configure the assignment using a CSV file with a tabular structure. Each row in the table contains two patterns and an entity name. The table can optionally contain the entity's custom classifications.

{% hint style="info" %}
When you use IP address fields with **CIDR** notation in device organization rules, the IP value must represent the network address of the subnet.

When you upload the ruleset for the first time, there is a **delay** ranging from 20 to 60 minutes for data population, depending on the size of the CSV file.
{% endhint %}

<details>

<summary>Classless Inter-Domain Routing (<strong>CIDR</strong>) format requirements for IP-based rules</summary>

CIDR ranges defined using a host IP address within the subnet are not supported for device organization rules. The IP portion must align with the CIDR prefix, with all host bits set to **zero**.

For example:

* **Valid:** `10.136.16.0/21`
* **Invalid:** `10.136.16.1/21`

If the CIDR range does not start at the network address, the CSV file is accepted during upload, but devices are not matched to the entity.

</details>

<figure><img src="https://268444917-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxJSUDk9NTtCHYPG5EWs3%2Fuploads%2Fgit-blob-0f04aae7d7602c3ca5a5b39954c4a16381a49d60%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

### Example of a CSV file for device organization ruleset <a href="#productconfiguration-exampleofacsvfile.1" id="productconfiguration-exampleofacsvfile.1"></a>

Example of a comma-separated, assignment text file:

```
Field1,Pattern1,Field2,Pattern2,Entity,region
,,,,,Global Region
name,device-d*,,,FRANCE,EUROPE
name,device-1*,,,CANADA,AMERICAS
collector_string_tag,CH*,,,SWITZERLAND,EUROPE
collector_string_tag,US*,,,UNITED STATES,AMERICAS
name,*,,,Unassigned,Unassigned
```

Table showing the assignment rules from the text file above:

<table data-full-width="true"><thead><tr><th width="246">Field1</th><th width="135">Pattern1</th><th width="129">Field2</th><th width="106">Pattern2</th><th width="198">Entity</th><th>Region</th></tr></thead><tbody><tr><td></td><td></td><td></td><td></td><td></td><td>Global Region</td></tr><tr><td>name</td><td>device-d*</td><td></td><td></td><td>FRANCE</td><td>EUROPE</td></tr><tr><td>name</td><td>device-1*</td><td></td><td></td><td>CANADA</td><td>AMERICAS</td></tr><tr><td>collector_string_tag</td><td>CH*</td><td></td><td></td><td>SWITZERLAND</td><td>EUROPE</td></tr><tr><td>collector_string_tag</td><td>US*</td><td></td><td></td><td>UNITED STATES</td><td>AMERICAS</td></tr><tr><td>name</td><td>*</td><td></td><td></td><td>Unassigned</td><td>Unassigned</td></tr></tbody></table>

Each row in the table contains two patterns, an entity name, and optional additional custom classifications. To satisfy a rule, a pattern must match the corresponding field. The system establishes rule precedence from the top to the bottom of the table. This requires you to be more specific with the device assignment at the top of the table and more general at the bottom.

Suppose you have a device with the `name` as `device-d100` and `collector_string_tag` as `CH10`. This device would match both the first and the third rules. Since the system evaluates the `device-d100` rule first, the device would be assigned to Entity `FRANCE` and Global Region `EUROPE`.

The first five columns are mandatory:

* **Field1:** Data for the first field used for the assignment (See [Supported values for Field1 and Field2](#supported-values-for-field1-and-field2-1) on this page.)
* **Pattern1:** The pattern for the first field
* **Field2:** Data for the second field used for the assignment (See [Supported values for Field1 and Field2](#supported-values-for-field1-and-field2-1) on this page.)
* **Pattern2:** The pattern for the second field
* **Entity**: The name of the target entity

In addition to the mandatory columns, add up to six custom columns for classifications.

The system uses the header row to create the NQL ID of the classification. Those values cannot contain spaces or special characters. The values in the second row correspond to the display names.

<figure><img src="https://268444917-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxJSUDk9NTtCHYPG5EWs3%2Fuploads%2Fgit-blob-2c37b838d09276d49544a0396acfe1bc44efb7a9%2Flocation-investigation.png?alt=media" alt="Difference between an NQL ID and a display name"><figcaption></figcaption></figure>

1. **#region** is the NQL ID.
2. **Global Region** is the display name of the NQL ID of the classification.

#### **Supported values for Field1 and Field2:**

* **name:** The hostname of the device.
* **collector\_tag:** The tag number assigned to Collector during its installation. The system only matches the exact number.
* **collector\_string\_tag:** The label assigned to Collector during its installation. This value supports pattern matching.
* **configuration\_tag:** Configurable label that identifies a group of devices. Set the value of this field using the [Enrichment API](https://docs.nexthink.com/api/enrichment). This value supports pattern matching.
* **dn:** The distinguished name of the device, as reported by Collector. The device must be part of an Active Directory domain. The format of the distinguished name reported by Collector is the standard sequence of `attribute=value` elements connected by commas, from the most specific to the most general attribute. For example, `CN=ex01,OU=Computers,DC=example,DC=org`
* **ad\_site:** The Active Directory site on which the device is located. The **name**, **collector\_string\_tag**, **dn** and **ad\_site** fields support character pattern matching. To define the associated string pattern, use the following wildcards:
  * The `?` character substitutes a single character.
  * The `*` character substitutes zero or more characters.
* **ip:** The last public IP address of the device (see `public_ip.ip_address` in [nql-data-model](https://docs.nexthink.com/platform/understanding-key-data-platform-concepts/nql-data-model "mention")). As a pattern for the field, specify either:
  * A single IP address in dot-decimal notation, for example `192.168.10.1`
  * A subnet in CIDR notation, for example `192.168.10.0/24`
* **primary\_local\_ip:** The last local IP of the device for the primary physical network adapter (see `connectivity.last_local_ip` in [nql-data-model](https://docs.nexthink.com/platform/understanding-key-data-platform-concepts/nql-data-model "mention")). Specify patterns in the same way you specified them for the **ip** field.
* **collector\_local\_ip**: The local IP used for the traffic between the endpoint and the Nexthink instance (see `collector.local_ip` in [nql-data-model](https://docs.nexthink.com/platform/understanding-key-data-platform-concepts/nql-data-model "mention")). Specify patterns in the same way you specified them for the **ip** field.
* **wifi\_ssid:** The WiFi network name (SSID) associated with the primary network adapter. This value supports pattern matching.

{% hint style="info" %}
Enable geolocation before starting to build rules based on public IP addresses.

To use the `wifi_ssid` tag, disable the following [Collector parameter](https://docs.nexthink.com/platform/configuring_nexthink/bringing-data-into-your-nexthink-instance/deploying-nexthink-in-non-vdi-environment/installing-collector/windows-collector-references/collector-msi-parameters-reference-table#collectormsiparametersreferencetable-optionalparameters): `ANONYMIZE_WIFI_NETWORK`
{% endhint %}

#### Considerations for CSV file for device organization ruleset <a href="#productconfiguration-considerations.1" id="productconfiguration-considerations.1"></a>

Ensure that your CSV configuration file meets the following criteria:

* The file size is less than 5MB.
* The file encoding is UTF-8.
* A comma is the field separator.
* Field delimiters are optional and quotes `"` are the only allowed delimiter type.
* There are no entity values and no classification values with an empty string or `-`.
* The maximum length of entity values and classification values is 50 characters.
* The total number of rules or rows is less than 40,000.
* The total number of distinct entities across the whole file is less than 2,000.
* The total number of custom classification columns must not exceed 6.
* A catch-all rule with `Field1=name` and `Pattern1=*` is entered for the last row of the table.
* The same entity cannot belong to multiple custom classifications. If an entity value appears on several lines, its classifications must be identical across all lines.

**Example:** The system will reject the following assignment rule because Entity FRANCE is incorrectly assigned to both EUROPE and AMERICAS on two different lines.

| Field1 | Pattern1   | Field2 | Pattern2 | Entity | Region                                              |
| ------ | ---------- | ------ | -------- | ------ | --------------------------------------------------- |
|        |            |        |          |        | Global Region                                       |
| name   | device-d\* |        |          | FRANCE | <mark style="background-color:red;">EUROPE</mark>   |
| name   | device-e\* |        |          | FRANCE | <mark style="background-color:red;">AMERICAS</mark> |

If any of these checks fail, the file selection will revert to the previously uploaded file. Only when you fix the errors, will you be able to unblock the upload.

{% hint style="info" %}
To prevent programs from automatically adding extra characters when saving, use plain text editors like Notepad++ or Sublime Text to edit your CSV file.
{% endhint %}

### **Updating custom classifications**

Update custom classifications by uploading a revised CSV file that best reflects your organizational structure. You can:

* Delete the entire column to remove an existing custom classification.
* Include a new column to add a new custom classification.

Once the new CSV is uploaded, the old custom classifications are removed from the data model and are no longer suggested by autocomplete.

{% hint style="warning" %}
Updating custom classifications may affect the results of existing NQL queries relying on organizational data. Ensure that you review and update these NQL queries after making changes to the custom classifications.

[View domain](https://docs.nexthink.com/platform/user-guide/administration/account-management/roles/view-domain) permissions rely on organization data, including custom classifications. Changing the assignment rules may affect the scope of data available to users with limited View domain permissions.

Be sure to revise profiles with limited View domain access after making changes to the custom classifications.
{% endhint %}

***

## Configuring User organization

**User organization** maps users to your organizational employee groups—as defined by your company hierarchy or holacracy—matching values from your HR management tool.

To define user organizational fields, from the **Administration** > **Product configuration** > **Device and user classification** tab, under **User organization**:

{% stepper %}
{% step %}

#### Create user organization fields

Add up to six user organization fields representing HR hierarchy or groups:

* Add a new user organization field, including its description, for example: **Business unit**.
  * The system automatically generates an **NQL ID** for the created field: `business_unit`.
* Drag and drop the created user-organization-field items to order them according to your company hierarchy.

Use case example: user organization fields serve as custom filters when monitoring AI tools usage per group of employees.

{% hint style="warning" %}
You should [#enrich-the-user-organization-fields](#enrich-the-user-organization-fields "mention") as new fields are present in the data model, but without values.

When using Nexthink inbound connectors for data enrichment, schedule the connector to run at the earliest possible time. This minimizes delays caused by the connector’s scheduled recurrence.
{% endhint %}

<figure><img src="https://268444917-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxJSUDk9NTtCHYPG5EWs3%2Fuploads%2Fgit-blob-c77ecc3455394e539d338c8a833a20ddbc795b87%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### Enrich the user organization fields

To enrich user organization fields with data, use one of the following options:

* Field mapping using [inbound connectors](https://docs.nexthink.com/platform/configuring_nexthink/bringing-data-into-your-nexthink-instance/integrating-nexthink-with-third-party-tools/inbound-connectors)—see the image below—to access your employee-management application, such as Workday or Salesforce, and map employee attributes to the user organization fields.
  * To minimize delays, configure the inbound connector to run at the earliest possible time, as the data enrichment depends on the connector's scheduled recurrence.
* Nexthink [Enrichment API](https://docs.nexthink.com/api/enrichment) to update the values of user organization fields with attributes from outside sources.
* [Custom fields management](https://docs.nexthink.com/platform/user-guide/administration/content-management/custom-fields-management#customfieldsmanagement-updatingcustomfieldsbyimportingacsvfileimportcsv) to update user organization fields by uploading a CSV file with user information.
* [Edition of custom fields](https://docs.nexthink.com/platform/user-guide/administration/content-management/custom-fields-management#customfieldsmanagement-editingcustomfieldsontheinvestigationspageeditcf) from Investigations to manually update user organization fields with user information.

The example below uses an inbound connector for Entra ID to map the user organizational field—**Business unit**—to a chosen **Entra ID field**.

Refer to the [Connector for Microsoft Entra ID (Azure AD)](https://docs.nexthink.com/platform/configuring_nexthink/bringing-data-into-your-nexthink-instance/integrating-nexthink-with-third-party-tools/inbound-connectors/connector-for-microsoft-entra-id-azure-ad#connectorformicrosoftentraid-azuread-fieldmapping) for field mapping procedure details.

<figure><img src="https://268444917-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxJSUDk9NTtCHYPG5EWs3%2Fuploads%2Fgit-blob-0102eef212b1ac8c01866099012a4501e50669ad%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### Validate the user organization field

Validate the user organization custom field by running the NQL query from Investigations, aggregating a group of users matching the specific HR hierarchy—in this example, the `business_unit`: EMEA Finance.

```
users
| where user.organization.#business_unit == "EMEA Finance"
```

{% endstep %}
{% endstepper %}

***

## NQL fields and examples <a href="#productconfiguration-nqlexamples" id="productconfiguration-nqlexamples"></a>

Location and ownership fields are available in the data model at two levels:

* As **Device or user property**: the fields return the current user or device organization unit and location of the device.
* As **Event context**: the context field returns the organization unit and location at the time of the event.

The following table summarizes the corresponding fields.

<table data-full-width="true"><thead><tr><th width="276"></th><th>Object property</th><th>Event context</th></tr></thead><tbody><tr><td><strong>Public IP geolocation</strong></td><td><ul><li><code>device.public_ip.country</code></li><li><code>device.public_ip.state</code></li><li><code>device.public_ip.city</code></li></ul></td><td>–</td></tr><tr><td><strong>Rule-based device location</strong><br><br>* See description below table</td><td><ul><li><code>device.location.type</code></li><li><code>device.location.site</code></li><li><code>device.location.state</code></li><li><code>device.location.country</code></li></ul></td><td><ul><li><code>context.location.type</code></li><li><code>context.location.site</code></li><li><code>context.location.state</code></li><li><code>context.location.country</code></li></ul></td></tr><tr><td><strong>Rule-based device organization</strong></td><td><ul><li><code>device.organization.entity</code></li><li><code>device.organization.#customClassification</code></li></ul></td><td><ul><li><code>context.organization.entity</code></li><li><code>context.organization.#customClassification</code></li></ul></td></tr><tr><td><strong>User organization</strong></td><td><ul><li><code>user.organization.#customClassification</code> </li></ul></td><td>–</td></tr></tbody></table>

**Description:**

For each device, the system tries to find a rule in the CSV file. If the device matches a rule, the system gets location data in one the following ways:

* If the rule has data for `Location Type` and one or more of the `Site`, `State,` and `Country` fields, then the system takes location data from the pertaining field. if any of these fields contain data, the system uses rule-based location data and any empty fields will show up as empty values in the query.
* If the rule has data only in the `Location Type` field, and `Site`, `State,` and `Country` fields are empty, then the system uses geolocation for location data.

See the following table for further clarification:

<table data-header-hidden data-full-width="false"><thead><tr><th width="266"></th><th></th><th></th></tr></thead><tbody><tr><td></td><td>Data in <code>Location Type</code><br><br>Data in <code>Site</code>, <code>State</code>, or <code>Country</code>, or all</td><td>Data in <code>Location Type</code><br><br><strong>No</strong> data in <code>Site</code>, <code>State,</code> and <code>Country</code></td></tr><tr><td>Rule-based location</td><td>✓</td><td></td></tr><tr><td>Geolocation</td><td></td><td>✓</td></tr></tbody></table>

### Use cases: Querying product configuration fields <a href="#productconfiguration-investigateexecutioncrashes" id="productconfiguration-investigateexecutioncrashes"></a>

The following NQL examples employ the product configuration features.

#### Geographical distribution of Salesforce users <a href="#productconfiguration-geographicaldistributionofsalesforceusers" id="productconfiguration-geographicaldistributionofsalesforceusers"></a>

Find the geographical distribution of Salesforce users:

```
web.events
| where application.name == "Salesforce*"
| summarize Number_of_users = user.count() by context.location.country, context.location.state, context.location.site
| sort Number_of_users desc
```

#### Investigate execution crashes using device location at the time of event <a href="#productconfiguration-investigateexecutioncrashes" id="productconfiguration-investigateexecutioncrashes"></a>

Investigate the number of execution crashes on all devices during the last 7 days to spot a potential geographical trend. Use `context.location` to see the device location at the time of the execution crashes. The query retrieves data from the `context.location` field, which stores the device location at the time of the event.

<pre><code><strong>execution.crashes during past 7d
</strong>| summarize total_crashes=number_of_crashes.sum() by context.location.country, context.location.state, context.location.site
</code></pre>

#### Investigate WiFi network quality using event context and current device location

1. See the sites with bad connectivity events in the past using the following query with `context.location`. The following query retrieves data from the `context.location` field, which stores the device location at the time of the event:

```
connectivity.events during past 3d
| where (connectivity.event.wifi.signal_strength.avg.rating !in [good, null] and context.location.site != null)
| summarize n_devices = count() by connectivity.event.wifi.signal_strength.avg.rating, context.location.site
```

2. Now we know if a certain site is prone to bad connectivity. Let's see the WiFi quality within that location, broken down by the adapter type, to look for the potential root cause. To do this, the following query uses `device.location`:

```
connectivity.events during past 1h
| where device.location.site == "site_with_bad_history"
| summarize n_devices = count() by connectivity.event.wifi.signal_strength.avg.rating, connectivity.event.primary_physical_adapter.type
```

#### Filter devices by organizational entity <a href="#productconfiguration-filterdevicesbyorganizationalentity" id="productconfiguration-filterdevicesbyorganizationalentity"></a>

Filter devices by `entity` to target them within a specific part of the organization:

```
devices 
| where organization.entity == "SWITZERLAND"
```

#### Filter users by organizational unit <a href="#productconfiguration-filterdevicesbyorganizationalentity" id="productconfiguration-filterdevicesbyorganizationalentity"></a>

Filter users by `#`team to target them within a specific part of the organization:

```
users
| where organization.#team== "Product"
```

#### Compare DEX scores by custom region and location type <a href="#productconfiguration-comparedexscoresbycustomregionandlocationtype" id="productconfiguration-comparedexscoresbycustomregionandlocationtype"></a>

Break the DEX score down by `#region` and `location.type` to ensure digital experience consistency across the organization.

```
dex.scores during past 7d
| summarize c1 = value.avg() by context.organization.#Region, context.location.type
```