Support

Product configuration

The Device and user classification tab in Product configuration allows you to determine how the system classifies devices and users within 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 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.

Accessing Administration > Product configuration > Device and user classification requires administrator permissions.

Configuring Device location

Device location enables you to know where a device is at the time of an event to help 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, which is 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

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

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.

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 leaves the Nexthink platform. Nexthink has its own instance of the geolocation database and performs the geolocation lookup internally.

Defining Rule-based location

The Nexthink platform includes a rule-based assignment process that allows the system to determine where a device is located. 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.

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

Refer to Supported values for Field1 and Field2 on this page for more information.

Table showing the assignment rules from the text file above:

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

  • 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 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 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

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

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. 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 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

  • 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 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 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.

Enable geolocation before starting to build rules based on public IP addresses.

To use the wifi_ssid tag, disable the following Collector parameter: ANONYMIZE_WIFI_NETWORK

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 2,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.

To prevent programs from automatically adding extra characters when saving, use plain text editors like Notepad++ or Sublime Text to edit your CSV file.

Configuring Device organization

Organizations still using classic hierarchies should migrate to Device organization custom rulesets.

Refer to the Entities and Hierarchies to Rule-based Organization documentation for migration steps.

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.

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.

Example of a CSV file for device organization ruleset

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:

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

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:

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.

Difference between an NQL ID and a display name

  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. 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). 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). 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). 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.

Enable geolocation before starting to build rules based on public IP addresses.

To use the wifi_ssid tag, disable the following Collector parameter: ANONYMIZE_WIFI_NETWORK

Considerations for CSV file for device organization ruleset

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

EUROPE

name

device-e*

FRANCE

AMERICAS

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.

To prevent programs from automatically adding extra characters when saving, use plain text editors like Notepad++ or Sublime Text to edit your CSV file.

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.

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 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.

Configuring User organization

User organization fields serve as custom filters when monitoring AI tools usage per group of employees. Refer to the Configuring AI tools documentation for more information.

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:

1

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.

2

Enrich the user organization fields

The created user organization fields are available in the data model, but without values.

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

  • Field mapping using 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.

  • Nexthink Enrichment API to update the values of user organization fields with attributes from outside sources.

  • Custom fields management to update user organization fields by uploading a CSV file with user information.

  • Edition of custom fields 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) for field mapping procedure details.

3

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"

NQL fields and examples

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

  • As Device property: the fields return the current ownership and location of the device.

  • As Event context: the context field returns the ownership and location at the time of the event.

The following table summarizes the corresponding fields.

Device property
Event context

Public IP geolocation

  • device.public_ip.country

  • device.public_ip.state

  • device.public_ip.city

–

Device location * See description below table

  • device.location.type

  • device.location.site

  • device.location.state

  • device.location.country

  • context.location.type

  • context.location.site

  • context.location.state

  • context.location.country

Rule-based organization

  • device.organization.entity

  • device.organization.#customClassification

  • context.organization.entity

  • context.organization.#customClassification

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:

Data in Location Type Data in Site, State, or Country, or all

Data in Location Type No data in Site, State, and Country

Rule-based location

✓

Geolocation

✓

Use cases: Querying product configuration fields

The following NQL examples employ the product configuration features.

Geographical distribution of Salesforce users

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

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.

execution.crashes during past 7d
| summarize total_crashes=number_of_crashes.sum() by context.location.country, context.location.state, context.location.site

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

  1. 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

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

devices 
| where organization.entity == "SWITZERLAND"

Compare DEX scores by custom region and location type

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 device.organization.#region, context.location.type

Last updated

Was this helpful?