Introducing the NXQL API (classic)

The NXQL API, also sometimes referred to as the Web API V2, is an HTTPS service that you invoke by issuing a POST or GET HTTP request to Engine via the URL:

https://<Nexthink_Instance_FQDN>/2/query

The service answers NXQL queries to the in-memory Engine database with a list of records in the selected output format.

A request expects the following parameters:

query

The NXQL query to execute.

platform

Specifies the target platform of the query. Should the query target multiple platforms, supply the argument for as many platforms as required. Supported platforms are windows, mac_os and mobile.

format

The expected output format. Available formats are CSV, HTML, XML and JSON.

hr

(Optional) Boolean value that indicates whether the output should be human-readable. When true, numerical values in the response are adapted to their best-fitting units for better readability. The chosen units are also displayed along with the values. Not used in the JSON output format.

For instance, to execute the following NXQL query: 

(select (device_uid name) (from device))

To send a query to your Nexthink instance, you must specify its fully qualified domain name (FQDN). Use an NXQL API request with the format: 

https://<instance>-engine-X.<region>.nexthink.cloud/2/query?platform=windows&platform=mac_os&query=(select%20(device_uid%20name)%20(from device))&format=csv

The target Engine instance returns the list of unique identifiers and names of all Windows and macOS devices in CSV format.

Template parameters

Extra parameters p1, p2, etc. can be added to the query to replace placeholders %1, %2, etc. in the NXQL query. Use placeholders in place of the names of custom fields, names of categories or literal values for parameterizing queries that are used often.

For instance, the following NXQL query returns the name of all devices, as well as their associated keyword from a category that you pass as a parameter 

(select (name #%1) (from device))

Use the following NXQL API request to get the names of all devices and their Location keyword: 

https://<instance>-engine-X.<region>.nexthink.cloud/2/query?query=(select%20(name%20%23%251)%20(from%20device))&p1=Location&format=csv

Authentication

User account

Any account with Data Privacy set to none (full access) and the option Finder access enabled can make use of the NXQL API. Otherwise, the NXQL API will reject the credentials of the account. Moreover, only those users with the right to edit categories can perform updates through NXQL queries.

User credentials are verified with basic HTTP authentication. For a given user, the visibility and info levels are identical to those defined in their profile.

Modification of accounts

Note that any change that you make to an account is not immediately propagated to the Engine instances. The synchronization of all the Engine instances can take up to five minutes. You can then have some temporary inconsistencies regarding the permissions of the accounts. For example, if you remove Finder access from an account by changing its profile to prevent it from accessing the NXQL API, that account might still be able to query an Engine instance via the NXQL API for a few minutes before synchronization takes place and its credentials are invalidated.

OAuth

You can configure Nexthink to grant access to the NXQL API using the open standard for access delegation, OAuth. Contact Nexthink Support for more information.

HTTP Status Codes

The NXQL API returns:

• 200 OK
  The request is successful.

• 400 Bad Request
  The request is invalid.

• 401 Not Authorized
  No credentials are provided or if they are not valid.

• 403 forbidden
  If the NXQL API is not licensed.

Examples of how to use the NXQL API

Testing the NXQL API with the NXQL editor

The NXQL editor is a web-based user interface to the NXQL API. This useful editor lets you test the queries that you will later use in your integration projects. The NXQL editor is present in every Engine with the Integration toolkit and you can access it from your favorite web browser by typing in the following URL:

https://<instance>-engine-X.<region>.nexthink.cloud/2/editor/nxql_editor.html

To write a query in the NXQL editor:

1. Provide the user credentials. Type in the user name and password in the two text input boxes at the top. The access rights of the user associated to the supplied credentials apply to the query.

2. Select the platforms that your query targets by ticking the appropriate platform icons at the top right corner.

3. Type in your NXQL query inside the big text region in the middle.

   • If your query includes any placeholder for template parameters, specify the value of the parameters in the two text boxes below the query. Editor queries may include up to two template parameters.

4. (Optional) Tick Formatted to get a human-readable output (see hr parameter of NXQL API requests above).

5. Click Send.

Once you send your query, the editor displays the message Loading... while Engine is processing it. After a few seconds, depending on the speed of your connection, the complexity of your query and the load on Engine, the response appears below the Send button on the same page.

• Choose the maximum number of displayed rows with the Show x entries picker.

• Navigate through the result pages with the help of the buttons at the bottom right.

• Order the results by column in ascending or descending order by repeatedly clicking the title of the column.

• Click the Other formats options at the bottom left to get the results in CSV, HTML, XML or JSON format.

Using the NXQL API with wget

The NXQL API can easily be invoked using the classic UNIX tool wget. For example, to retrieve the names of all devices in CSV format write the following command:

> wget --quiet \
  --no-check-certificate \
  --user=nxdocsapi --password=This-Is_Just-An_Example \
  --output-document devices.csv \
  'https://<instance>-engine-X.<region>.nexthink.cloud/2/query?
   query=(select%20(id%20name)(from%20device))%20&
   format=csv&
   platform=windows&platform=mac_os'

Using the NXQL API with PowerShell

The NXQL API can be invoked using Windows PowerShell. However, since the standard Invoke-WebRequest CmdLet does not support self-signed certificates, you should use the CmdLet defined in the downloadable file Code-For-Invoke-Nxql.ps1. After saving this script, load it into your PowerShell environment. Make sure that your PowerShell execution policy is set to unrestricted.

To load the script, type in the following in the PowerShell console:

. ./Code-For-Invoke-Nxql.ps1

To retrieve the list of names of all the devices of any platform in CSV format, for example, execute the following command:

Invoke-Nxql -ServerName 192.168.2.3
  -UserName nxdocsapi -UserPassword This-Is_Just-An_Example
  -Platform windows,mac_os
  -Query "(select (name) (from device))" > devices.csv

To get the full command line options, type in:

Invoke-Nxql -?

Using the NXQL API with Power BI Desktop

Microsoft Power BI is a suite of interactive visualization tools that deliver analytical insights throughout your organization. Thanks to the NXQL API, feed Power BI with Nexthink data and graph the digital experience of end users on visually appealing charts.

First, ensure that the Windows device where you run Power BI Desktop trusts the server certificate of Engine:

• If you replaced the default certificate of Engine with a server certificate signed by a publicly-trusted CA, nothing else needs to be done, as Windows will usually trust the certificate.

• Otherwise, install the root certificate of the CA that signed Engine certificate in the Trusted Root Certification Authorities store of your Windows device, as explained here for devices that run Collector or Finder.

To invoke the NXQL API from Power BI Desktop:

1. Open Power BI Desktop.

2. Select Get Data from the top menu.

   1. Choose Web as the data source.

   2. In the From web dialog, type in your NXQL API query as URL, requesting XML as output format.

      • Remember that you can easily get this URL while editing your query in the NXQL editor by copying the link from the Other formats section at the bottom of the page.

   3. Click OK.

      • If the connection cannot be established because of a TLS error, verify that you imported the correct root certificate to trust the server certificate of Engine.

3. Type in your NXQL API credentials when prompted to do so.

4. In the Navigator, select the body to get the XML data from the Engine response.

5. Click Load.

The data source is now added. However, Power BI is unable to send authentication credentials again when using these parameterized queries. The solution is to divide the query into a base and a relative path:

1. In Power BI Desktop, select Edit Queries from the top menu.

2. Open the data source that calls the NXQL API and select Advanced Editor.

3. In the editor, look for the Source variable under the let keyword:Source=XML.Table(Web.Contents("https://<Nexthink_Instance_FQDN>/2/query? query=(select%20(id%20name)(from%20device))%20&format=xml" ...

4. Divide the URL of the query into a base and a relative path as follows: Source=XML.Table(Web.Contents("https://<Nexthink_Instance_FQDN>/2/", [ RelativePath="query?query=(select%20(id%20name)(from%20device))%20&format=xml" ]...

For each subsequent query, Power BI Desktop will use the credentials that you typed in when you first created the data source.