↓Skip to main content

Itential getAdaptersHealth API Call

·512 words·3 mins
Table of Contents

The getAdaptersHealth API endpoint allows us to retrieve the data and operational status for all configured adapters on an IAP instance. I typically use this to e.g. determine the proper IAG adapter to onboard a device with or to determine if an adapter is healthy (Status:RUNNING, Connection:ONLINE) as part of my pre-change checks.

The generic restCall task #

You can use the generic restCall task in IAP Automation Builder to send API calls to the local or a remote IAP server. This task enables you to send a query to the getAdaptersHealth API endpoint, which is part of the standard pronghorn-core group of API calls. There is currently no dedicated task available in Automation Builder to get all adapters and their operational status (IAP 2023.1). And the Itential IAP opensource adapter doesn’t contain this option either.

Example #

The following screenshot shows an example of how to use the restCall task to send an API call to the local IAP instance (127.0.0.1).

Image alt

uri https://127.0.0.1:3443/health/adapters
verb GET
user username
password password
headers leave blank
body see queryOptions section below

queryOptions #

The queryOptions determine what and how much data is returned by the getAdaptersHealth API call.

In this example I want to retrieve all Cisco DNA Center adapter instances on my IAP. The field I want to filter by is package_id and package ID for the DNAC adapters is @itentialopensource/adapter-dna_center.
The package ID is usually the name of the adapter prebuilt as shown in the NPM or GitLab repositories. Alternatively, you can also get this value by going to Admin Essentials > Adapters > yourAdapter, toggle on the Advanced View, and copy the model value that starts with @itential/ or @itentialopensource/.

Here is an example queryOptions template you can use to send as the body in the restCall task:

{
    "queryOptions": {
        "equals": "@itentialopensource/adapter-dna_center",
        "equalsField": "package_id",
        "skip": 0,
        "limit": 10
    }
}
equals Filter on a field. The value has to match exactly.
equalsField The field to match against.
skip Number of results to skip. Used for pagination. Default is 0.
limit The number of results returned.
sort Field to sort by. Default is name.
order Sort direction. 1 for ascending and -1 for descending.

Check out the schema definition for more options like contains or startsWith.

Use filter options like equals/equalsField, contains/containsField, or startsWith/startsWithField to retrieve only the adapter data you are looking for.

Example Workflow #

Image alt

Example Input/Output #

Input

{
  "uri": "https://127.0.0.1:3443/health/adapters",
  "verb": "GET",
  "user": "* * * * *",
  "password": "* * * * *",
  "headers": "",
  "body": {
    "queryOptions": {
      "equals": "@itentialopensource/adapter-dna_center",
      "equalsField": "package_id",
      "skip": 0,
      "limit": 10
    }
  },
  "responseHeaders": false
}

Output (truncated)

{
  "response": {
    "body": {
      "results": [
        {
          "id": "dnac-lab.domain.com",
          "package_id": "@itentialopensource/adapter-dna_center",
          "version": "0.6.2",
          "type": "Adapter",
          "description": "This adapter integrates with system Dna_center",
          "state": "RUNNING",
          "connection": {
            "state": "ONLINE"
          },
          "uptime": 491162.191712545,
          "memoryUsage": {
            "rss": 256696320,
            "heapTotal": 109891584,
            "heapUsed": 103882776,
            "external": 38782589,
            "arrayBuffers": 37866102
          },
          "cpuUsage": {
            "user": 352368455,
            "system": 67758551
          },
          "pid": 2323470,
          "logger": {
            "console": "debug",
            "file": "debug",
            "syslog": {}
          },
          "routePrefix": "Dna_center",
          "prevUptime": 491134.916105273
        }
      ],
      "total": 4
  }
}