Itential getDevicesFiltered API Call

Table of Contents

The getDevicesFiltered task allows us to retrieve the inventory data for one or more configured devices in Configuration Manager. I typically use this to e.g. retrieve a list of devices of a certain OS type.
The official API documentation for this endpoint was not really clear to me and it took some testing and playing with different query parameters to figure out how to properly use this task.

The getDevicesFiltered task #

You can use the getDevicesFiltered task, which is part of the ConfigurationManager tasks group in IAP Automation Builder, to retrieve data for one or multiple devices. The critical piece is to set the proper query parameters using the options object to filter and limit the results. This is especially important for large environments with thousands of devices.

Example #

The following screenshot shows an example of how to use the getDevicesFiltered task.


options	Object with filters and query params.

options #

The options object determines what and how much data is returned by the getDevicesFiltered API call.

In this example I want to retrieve the first ten devices from Configuration Manager that have an OS Type value of cisco-asa.

Here is an example template you can use to send as the options object in the getDevicesFiltered task:

{
    "limit": 10,
    "start": 0,
    "filter": {
        "ostype": "cisco-asa"
    },
    "exactMatch": true
}


limit	The number of results returned.	required
start	Number of results to skip. Used for pagination.	optional
filter	Filter on a field. The object can take multiple keys.	optional
sort	Field(s) to sort by.	optional
order	Sort direction; ascending or descending.	optional
exactMatch	Boolean that indicates if an exact result will be returned or not.	seems to be required despite the documentation not listing it as such

Check out the schema definition for more filter and query options.

exactMatch seems to be a required parameter in IAP 2023.1 and earlier. Add this parameter to your options object if you receive server 500 errors when executing the getDevicesFiltered task.

Example Input/Output #

Input

{
  "options": {
    "limit": 10,
    "start": 0,
    "filter": {
      "ostype": "cisco-asa"
    },
    "exactMatch": true
  }
}

Output (truncated)

{
  "devices": {
    "entity": "device",
    "total": 30,
    "totalByAdapter": {
      "itential-iag1-dev.domain.com": 10,
      "itential-iag2-dev.domain.com": 10,
      "itential-iag3-dev.domain.com": 10
    },
    "unique_device_count": 23,
    "return_count": 10,
    "start_index": 0,
    "list": [
      {
        "user": "username",
        "port": "22",
        "password": "************",
        "ostype": "cisco-asa",
        "ipaddress": "10.11.12.13",
        "device-type": "network_cli",
        "name": "testdevice1",
        "host": "itential-iag1-dev.domain.com",
        "actions": [
          "deleteDevice",
          "getConfig",
          "getDevice",
          "getDevicesFiltered",
          "getOperationalData",
          "isAlive",
          "loadConfig",
          "restoreConfig",
          "runCommand",
          "setConfig"
        ],
        "origins": [
          "itential-iag1-dev.domain.com",
          "itential-iag2-dev.domain.com"
        ]
      }
    ]
  }
}