Please note that this is a Technical Preview and consequently that all documentation, content, or updates may contain errors and are provided for limited evaluation only. The Technical Preview, the documentation, and any updates are provided on an ‘as-in’ and ‘as-available’ basis without warranty of any kind, whether express, implied, by operation of law or otherwise. Nexthink specifically disclaims all implied warranties of merchantability, fitness for a particular purpose and non-infringement.

Overview

The NQL conditions field supports most of the syntax that is available in NQL. Nonetheless, this component cannot support the whole range of operators that NQL provides.

The main goal of this component is to declare the filters using NQL syntax for alerts or events that trigger a webhook.

Building the NQL conditions query

NQL tables

The official NQL documentation states, the query should start by specifying the name of the table to be used.

The list of tables that are allowed in the NQL conditions field are:

NQL Object

Available in Webhook

diagnostic.alerts

Yes

execution.starts

No

execution.crashes

No

campaign.responses

No

campaign.name_of_campaign

No

remote_action.execution

No

remote_action.id_of_remote_action

No

device_performance.boots

No

device_performance.crashes

No

device_performance.hard_reset

No

session.logins

No

session.logouts

No

session.connect

No

session.disconnect

No

session.locks

No

session.unlocks

No

collector.updates

No

There is one characteristic that renders all the previous events unique, which is that all of them are Punctual events. This means that they occur at a specific point in time and do not have a span, as may be the case for other events such as appex.transactions

No error message is displayed when you reference an NQL table other than what is listed above for the NQL Conditions field. The Webhook is saved correctly and an error occurs only after the condition is evaluated. In the future, the component will be adjusted to display a message when an NQL table is not allowed to be used.

NQL operators

As mentioned in the section above, not all NQL operators are at the customer’s disposal. Since you are dealing with punctual events, there is a subset of NQL operators that are valid and those that are not. See the table below:

NQL Operator

Type

Available in Webhook

where

selection

Yes

and

filtering

Yes

or

filtering

Yes

list

projection

No

compute … by

computation

No

limit

selection

No

asc / desc

filtering

No

during past

selection

No

from … to …

selection

No

summarize

computation

No

summarize by …

computation

No

Regardless of the type of NQL query that you are creating, it is important to pay attention to the table and the properties that can be used.

The list of fields for each of the tables allowed in the NQL conditions are listed below:

NQL Object

NQL property

Property Type

Operator

Example

diagnostic.alerts

alert_config.name

String

==, !=, contains, !contains

alert_config.name == “Alert Name”
alert_config.name contains “Alert Name”

diagnostic.alerts

alert_config.multiple_context

Boolean

==, !=

alerts.multiple_context == true

diagnostic.alerts

alert_config.threshold

Float / Integer

>, <, >=, <=, ==, !=

alerts.threshold >= 4.0

diagnostic.alerts

alert_config.priority

Enum

==, !=

alert_config.priority == CRITICAL

diagnostic.alerts

alert_config.tags

String Array

contains, !contains

alert_config.tags contains “ITSM”

If you use an NQL table or field as part of a query that is not listed in the table above, it won’t be processed appropriately, even if its syntax is well written. In future, there will be more flexibility to incorporate more tables and fields into the NQL conditions editor.

Examples of queries

Examples of valid queries for NQL conditions field

Trigger a webhook when an alert with the name “MS Teams crashes in the last 24 hours” is triggered:

diagnostic.alerts
| where alert_config.name == “MS Teams crashes in the last 24 hours”
CODE

Trigger a webhook when an alert with tags Webhook and ServiceNow, and with critical priority is triggered:

diagnostic.alerts
| where alert_config.tags contains “Webhook” 
and alert_config.tags contains “ServiceNow”
and alert_config.priority == HIGH 
CODE

Trigger a Webhook when an alert with tags “Webhook-4me” or alert name is “MS Teams crashes for SD” is triggered:

diagnostic.alerts
| where alert_config.tags contains “Webhook-4me” 
or alert_config.name == “MS Teams crashes for SD”
CODE

Trigger a Webhook when an alert with tags “Outlook” or alert name is “MS Teams crashes for SD”, and configured threshold that is greater than 5:

diagnostic.alerts
| where alert_config.tags contains “Outlook”
or alert_config.name == "MS Teams crashes for SD"
and alert_config.threshold > 5
CODE

Example of invalid queries in NQL conditions field

Using NQL tables that are not valid:

device_performance.activities during past 7d
| where events.normalized_cpu_usage > 14
CODE

Using properties that are not available:

diagnostic.alerts
| where alerts.trigger_time == "2021-10-23" and alerts.context contains "JIRA" 
CODE

Using operators that are not available:

diagnostic.alerts 
| with appex.errors during past 7d 
| where alerts.trigger_time == "2021-10-23" and alerts.context contains "JIRA"
| list appex.errors.count.sum(), alerts.id
CODE