Custom fields management

Custom fields allow you to extend the NQL data model with additional fields. There are three types of custom fields:

Manual custom fields allow you to enrich inventory objects by importing data from external systems for reporting and analytics. You can assign tags to objects in the Nexthink web interface to target specific campaign users or create pilot groups for change management.
Computed custom fields allow you to track values defined with an NQL query, saving time for frequently executed queries. Adding computation as an element in the data model facilitates using the results in various product parts, such as Checklists.
Rule-based custom fields allow you to automatically sort objects according to pre-defined criteria, each expressed as an NQL query. You can break down datasets according to the most relevant axes and set up frequently-used filters which are easy to maintain and access in Investigations.

Custom field names are prefixed by the # character, making them identifiable in an NQL query.

Nexthink platform restricts the number of custom fields for each type. You can configure up to:

100 manual custom fields.
200 computed custom fields.
200 rule-based custom fields.

Accessing custom fields

Select Administration from the main menu.
Click on Custom fields in the navigation panel under the Content Management section.

If you don’t see the menu entries, ensure your profile has the proper permissions.

Managing custom fields

The Custom fields administration page lists all the custom fields organized in a table.

Hover over each custom field to reveal the action menu on the right side of the table. The action menu options are:
- Edit: Configure a custom field.
- Delete: Remove a custom field.
- Export: Export a custom field in the JSON file format to share with other instances of the Nexthink cloud instance.
- Copy NQL ID: Use the NQL ID when writing NQL queries to retrieve information from a custom field.

In the top-right corner of the page you can find 3 buttons to do different tasks:
- Click on the New custom field button to add and configure a custom field. Refer to the Creating a new custom field section for more information.
- Click on the Import button to import a custom field in the JSON file format.
- Click on the action menu in the top-right corner of the page and select Update values. Refer to the Updating custom fields by importing a CSV file section for more information.

Creating a new custom field

Click on the New custom field button to add and configure a custom field. This opens the Draft page.

Fill out the fields under General according to the table below:

Field	Description
Name	The name that appears on the Investigations page.
NQL ID	The system references custom fields in queries using NQL ID. Nexthink suggests an NQL ID based on the custom field name. The NQL ID cannot be edited after saving the custom field.
Description (optional)	Enter an optional text to help other users understand the meaning of the custom field.

Select a custom field Type. There are 3 possible options:
- Manual Type with an Object
- Computed Type with an NQL query
- Ruled-based Type with an Object and Rules

Choosing Manual Custom field Type

Select Manual under Type.
From the Object drop-down menu, choose the object to which the system applies the custom field: Device, User, Binary or Package.

Refer to the Setting values for manual custom fields section for more information.

Choosing Computed Custom field Type

Select Computed under Type.
Write an NQL query that returns a single-column table with the devices computation results in each row.

See the example below of a CPU Queue length (24h) custom field.

The following table displays the field inputs for the Computed Type example above:

Field	Input (example)
Name	CPU Queue length (24h)
NQL ID	`#cpu_queue_length_1hr` In the example above, even though the user updates the custom field name to a 24-hour timeframe, the NQL ID still reflects the initial 1-hour timeframe. Remember, The NQL ID cannot be edited after saving the custom field.
Description (optional)	Display the average length for the pash 24hrs. The higher the queue length, the lower the CPU performance. CPU queue length should be less than 1.5 times the number of logical processors available on the device for best performance.
NQL query	See query code below.

CODE

devices 
| include device_performance.events past 24h
| compute c1 = (cpu_queue_length.avg() / number_of_logical_processors.avg())
| list c1

Guidelines for writing NQL queries for computed custom fields

The query must target the devices collection.
The query must have exactly one include clause.
The system allows the where clause only after the include clause.
The query must have exactly one compute clause.
The query must end with a list clause and a single previously computed field.
The system does not allow the sort, limit, summarize or with clauses.
Once you save a computed custom field with a query, you cannot change the query to return a different data type.

Choosing Rule-based Custom field Type

Select Rule-based under Type to sort objects according to predefined criteria.
From the Object drop-down menu, choose the object to which the system applies the custom field: Device, User, Binary or Package.

Common use cases for rule-based custom fields include:

Classify device models as premium, mainstream or budget, based on their hardware specifications.
Classify devices based on their installed memory.
Classify users as internal or external, based on their name or email patterns.
Classify packages and binaries by their importance for business continuity.
Define a blocklist of packages or binaries for compliance.

A rule-based custom field can contain up to 20 rules.

You can drag and drop rule-based custom fields to change their order. The system evaluates rules from top to bottom.

The following attributes characterize each rule:

Rule attribute	Description
Value	The label attached to all objects that satisfy the rule.
Rating	A value judgment attached to the rule: Poor, Average or Good. By default, it is set to None.
NQL query	A query to be executed upon evaluation of the rule.

Consider the following constraints for NQL queries for ruled-based custom fields:

The query must target the object that the custom field is defined on. For instance, devices for a device custom field.
The query must have at least one where clause.
The with, include, summarize, compute and list clauses are not allowed.
Time selections such as during past, from and to are not allowed.
The query can only reference native object properties

Rule-based example of installed memory profile

This section displays an example of a rule-based custom field for classifying devices based on installed memory. These are the field inputs and rules:

Name: Memory Profile
NQL ID: #memory_profile
Description: Classify devices based on their installed memory.
Object: Device

Rule 1	Value: Installed_memory_0_to_8_GB Rating: Poor NQL query: `devices \| where hardware.memory <= 8GB`
Rule 2	Value: Installed_memory_8_to_16_GB Rating: Average NQL query: `devices \| where hardware.memory <= 16GB`
Rule 3	Value: Installed_memory_16_to_32_GB Rating: Good NQL query: `devices \| where hardware.memory <= 32GB`
Rule 4	Value: Installed_memory_over_32_GB Rating: Good NQL query: `devices \| where hardware.memory > 32GB`

Considering the rules from above, the system tags a device with 16GB of installed memory as Installed_memory_8_to_16_GB, as Rule 2 is the first rule satisfied by the condition of the NQL query.

From the Investigations page, you can execute an investigation running an NQL query using your ruled-based custom fields.

The following query returns the number of execution crashes per device, according to the device’s memory profile:

CODE

execution.crashes during past 30d
| summarize crash_ratio = count()/device.count() by device.#memory_profile

Instead of breaking down the results by memory, you can also break them down by the ratings set in the rules: poor, average and good.

In this case, Nexthink rates the devices with Installed_memory_16_to_32_GB and Installed_memory_over_32_GB together as good.

CODE

execution.crashes during past 30d
| summarize crash_ratio = count()/device.count() by device.#memory_profile.rating

Setting values for manual custom fields

Once you create a custom field, you can set its values in the following ways:

Edit options on the Investigations page.
Update values from the actions menu of the Custom fields administration page.
Enrichment API, refer to the Nexthink API Documentation for more information.

The following requirements apply independently of the option you choose to set the values:

UTF-8 characters are supported, except the backslash \ and double quote " characters.
A maximum of 64 characters are allowed per field value.

Editing custom fields on the Investigations page

You may edit custom fields on the Investigation page by accessing the following:

The action menu
The action bar
The Export results option (bulk editing)

Editing custom fields with the action menu

From the Investigations page:

Select Edit from the action menu for the custom field in the NQL results table.
Enter the value for the New value field in the Edit custom field modal.
Click Done to save the change.

Editing custom fields with the action bar

From the Investigations page:

Select the Edit option in the action bar at the bottom of the page for the results of the NQL query on the object type you wish to edit, for example, on devices.

If you don’t see the Edit option, ensure your profile has the right permissions.

In the Edit custom field modal:
- Select a custom field from the Custom field drop-down menu.
- Enter a new value into the New value text field.
- Click Done to save changes.

The action bar does not allow bulk editing of large sets of investigation results that are not fully loaded and visible on the page.

Bulk editing custom fields by exporting results

From the Investigations page:

Run an investigation with the ID field and the custom fields to edit.
Export results as a CSV file.
Edit the custom field values using a spreadsheet editor.
Import the edited CSV file.

The CSV file example on this page describes the tabular configuration of the file. Additionally, the image below displays how to Export results from an investigation page.

Updating custom fields by importing a CSV file

From the Custom fields page:

Click on the action menu in the top-right corner of the page.
Select Update values to import several custom fields at once into the Nexthink web interface.

In the Update values dialog box select a valid CSV file ensuring it meets the following criteria:
- The file size is less than 5MB.
- The file encoding is UTF-8 (UTF-8-BOM is not supported).
- The backslash \ character is not supported.
- A comma is the field separator.
- Field delimiters are optional and quotes " are the only allowed delimiter type.

Example of a CSV file for updating custom fields

Configure a CSV file with a tabular structure to import your data.
- CODE
```
device.name,device.#custom_field1,device.#custom_field2
device-1,A1,B
device-2,A1,B
device-3,A2,B
device-4,A2,
```
- The values A1 or A2 are assigned to all devices for the first custom field.
- The value B is assigned to the first three devices for the second custom field.
- The value of #custom_field2 is not set for device-4. If previously set, this CSV file updates #custom_field2 value to NULL.
Follow these formatting rules:
- Headers are in an NQL ID format with an explicit object type, for example, device.name and device.#custom_field1.
- The file has at least one ID column. These IDs are accepted:
  - device: device.uid, device.name
  - user: user.uid, user.sid, user.upn
  - binary: binary.uid
  - package: package.uid

Prerequisite for user updates based on user.upn: UPN collection enabled at collector level, as cleartext. This can be achieved with the following Library content:

https://www.nexthink.com/library/#set-anonymization-features-windows

https://www.nexthink.com/library/collector-configuration#set-anonymization-features-macos

Permissions

To enable proper permissions for custom fields:

Select Administration from the main menu.
Click on Profiles from the navigation panel.
Click on the New Profile button in the top-right corner of the page to create a new profile.
- Or edit an existing profile by hovering over it and clicking on the edit icon to change the profile configuration.
In the Permissions section, scroll down to Administration and enable Manage all custom fields to allow users to create, edit and delete custom fields as well as set values for manual custom fields.
- The Manage all ratings permission is automatically granted for those with Manage all custom fields privileges (granting user rights for configuring rule-based custom fields).

Refer to the Profiles documentation for a detailed description of the permission options.