Software Metering API (classic)

Overview

To integrate program usage data with external systems, Portal provides an API to query the historical details of Software Metering dashboards.

The client of the Software Metering API must trust the certificate in the primary Appliance (Portal).

To authenticate the client, the Software Metering API uses Basic Authentication. Nexthink recommends creating a local account to exclusively authenticate clients of the API.

Finding out available metrics

To interactively look for Software Metering data that is available through the API:

  1. Point a web browser to the following address:

    https://<Portal_DNS_FQDN>/api/softwaremetering/v1​
    • Substitute <Portal_DNS_FQDN> for the actual name of Portal.

  2. Log in to the discovery tool of the Software Metering API as a user with the right to see software metering metrics (either because the user can see all metrics or because the associated software metering module is included in the roles of the user).

    • Type in the user credentials whenever asked by the web browser.

    • The discovery tool displays only the available metrics in the view domain of the user.

  3. Select a metric from the table.

  4. Select an available hierarchy.

  5. Optional: Select a program to restrict the output to a particular program.

  6. Optional: Select a node (below Path) to restrict the output to a node of the hierarchy. Repeat for each level of the hierarchy.

  7. Get the metric details for the entities where the package is installed or where the program is under usage and format is one of table (for an HTML table), csv, or json:

    • Installed (format)

    • Underusage (format)

Once you have reached the desired details of the metric, note down the URL built by the discovery tool to programmatically query the API later with the same request or use it as a base for your own requests.

Querying the API

To query the Software metering API, send a GET request to a URL that includes the following parameters:

ParameterDescriptionDefault value

metric

UID of the desired metric

(none)

hierarchy

Name of a hierarchy

The name of the first hierarchy in Portal

program

UID of the program to measure (binary object)

(none)

list

Type of to list in the output:

  • installed

  • underusage

installed

path

Name of a node in the hierarchy to limit the output. Chain several path elements to limit the output further down in the hierarchy levels.

The highest node in the view domain of the user

format

Output format, one of:

  • table (for an HTML table)

  • json

  • csv

table

Example of a query URL:

https://<Portal_DNS_FQDN>/api/softwaremetering/v1/details?​
metric=52fa2b8b-b35e-4d7a-9db3-830617c5b6b2&​
hierarchy=DefaultHierarchy&​
program=8b37ddb4-29fe-469a-bdc0-ca3497d7c7f9&​
list=installed&​
path=Europe&path=Switzerland&path=Lausanne&​
format=json

The Software Metering API uses Basic Authentication. To test the API from a Nexthink appliance, you can use curl, for instance:

curl https://<Portal_DNS_FQDN>/api/softwaremetering/v1/details?... -u username:password

Output of the Software Metering API

The output of the API is similar to the details of Software Metering metrics that you can explore in Portal. Two data fields are exclusively found on the API, though:

  • Entity

  • First date with package

Find below the complete list of outputs of the Software Metering API:

Output dataDescription

Device

The name of a device that has at least one of the packages installed.

Entity

The name of the entity to which the device belongs.

Average usage per day (seconds)

The average usage per day of significant binaries on the device, expressed in seconds.

Average executions per day

The average number of executions per day of significant binaries on the device.

First date with package

The date of first detection of the earliest detected package on the device.

Last activity

The date of last activity of the latest executed significant binary on the device.

Binaries

Lists the binaries that where used on the device. It is either a collection of the binaries used (output in json format), or a list of the significant binaries followed by yes, if the binary was actually used, and no, if the binary was not used (output in table or csv formats).


RELATED TASKS

RELATED REFERENCES

Last updated

#451: 2024.8-Overview of integration DOC

Change request updated