npm package: @itentialopensource/iag-device-connectivity
Description: This pre-built is used to check the device connectivity for a list of IAG devices that are in the inventory of an IAG instance and returns if the device is connected on IAG or not
Author: Itential Artifacts
Latest version: 1.0.3

# IAG Device Connectivity

- [IAG Device Connectivity](#iag-device-connectivity)
  - [Overview](#overview)
  - [Supported IAP Versions](#supported-iap-versions)
  - [Getting Started](#getting-started)
    - [Prerequisites](#prerequisites)
    - [Capabilities](#capabilities)
    - [How to Install](#how-to-install)
    - [Testing](#testing)
  - [Using this Pre-Built](#using-this-pre-built)
    - [Input Schema](#input-schema)
    - [Output Schema](#output-schema)
  - [Additional Information](#additional-information)

## Overview

The **IAG Device Connectivity** pre-built is used to check the device connectivity for a list of IAG devices that are in the inventory of an IAG instance and returns if the device is connected on IAG or not.

  - Estimated Run Time: < 1 minute for device(s)

## Supported IAP Versions

Itential pre-builts are built and tested on particular versions of IAP. In addition, pre-builts that work with devices are often dependent on certain orchestration systems (e.g. NSO and IAG). As such, these pre-builts will have dependencies on these other systems. This version of the IAG Update Device Details pre-built has been tested with:

  - IAP 2022.1.x

## Getting Started

These instructions will help you get a copy of the pre-built in your IAP instance for testing in your environment. Reading this section is also helpful for deployments as it provides you with pertinent information on prerequisites and capabilities.

### Prerequisites

Users must satisfy the following prerequisites to install and run this pre-built:

- Itential Automation Platform.
  - `^2023.1.x`
- An instantiated IAP IAG adapter.
- A device in an IAG instance.

### Capabilities

- Checks connectivity status of one or more devices of multiple device types onboarded to IAG (Currently only supports HTTP Request and Ansible device types)


### How to Install

To install this pre-built:

- Verify that you are running the documented [prerequisites](#prerequisites) in order to install the pre-built.

- Follow the instructions on the Itential Documentation site for [importing a pre-built](https://docs.itential.com/docs/importing-a-prebuilt-2).

### Testing

While Itential tests this pre-built and its capabilities, it is often the case the customer environments offer their own unique circumstances. Therefore, it is our recommendation that you deploy this pre-built into a development/testing environment in which you can test the pre-built.

## Using this Pre-Built

This pre-built can be run in as a standalone Operations Manager automation if wanting to check the device connectivity of one device or a [childJob task](https://docs.itential.com/docs/childjob-1) if wanting to check the device connectivity of multiple devices.

**Note**: The entry point to run this pre-built as a standalone Operations Manager automation is called `IAGDC: Check Device Connectivity`. The entry point to run this pre-built in a childJob task is called `IAGDC: Check Devices`. 

When running this pre-built, it depends on being provided proper input so that the device(s) can be discovered in IAG as expected and so that only the allowed inputs in IAG are being updated. The input to and possible outputs from this pre-built are described here.

### Input Schema

Ansible devices only need the device_name, inventory_type, and iag_adapter_instance field filled out. 

Example input for an Ansible device:
```json
{
  "device": [
    {
      "device_name": "deviceName",
      "inventory_type": "ansible",
      "iag_adapter_instance": "IAG",
      "host": null,
      "endpoint": null,
      "method": null,
      "params": null,
      "data": null,
      "headers": null,
      "cookies": null,
      "auth": null,
      "timeout": null,
      "allow_redirects": null,
      "proxies": null,
      "verify": null
    }
  ],
  "options": {
    "verbose": true
  }
}
```
HTTP Requests require the host, endpoint, and method to be filled out. Every other input is situational to the HTTP Request. HTTP Requests use the [sendRequest](https://apidocs.itential.com/2021.2/api/adapter-automation_gateway/sendRequest/) task to verify connectivity of the device. Example input for an HTTP Request:
```json
{
  "device": [
    {
      "device_name": null,
      "inventory_type": "http_requests",
      "iag_adapter_instance": "IAG",
      "host": "host_name",
      "endpoint": "/mgmt",
      "method": "GET",
      "params": null,
      "data": null,
      "headers": null,
      "cookies": null,
      "auth": {
        "username": "admin",
        "password": "admin"
      },
      "timeout": null,
      "allow_redirects": false,
      "proxies": null,
      "verify": false
    }
  ],
  "options": {
    "verbose": true
  }
}
```

The following table details the property keys of the input object.
| key                                      | type    | required | description |
|------------------------------------------|---------|----------|---------------------------------------------------------|
| device                          | array   | yes      | list of devices
| device.device_name              | string  | no       | device name for ansible device
| device.inventory_type           | string  | yes      | inventory type (ansible or http_requests)
| device.iag_adapter_instance     | string  | yes      | adapter IAP instance
| device.host                     | string  | no       | host name for HTTP request device
| device.endpoint                 | string  | no       | endpoint to append to the URL built from the HTTP request device
| device.method                   | string  | no       | request method for HTTP request device
| device.params                   | object  | no       | params for HTTP request device
| device.data                     | object  | no       | data for HTTP request device
| device.headers                  | object  | no       | headers for HTTP request device
| device.cookies                  | object  | no       | cookies for HTTP request device
| device.auth                     | object  | no       | authorization for HTTP request device
| device.timeout                  | object  | no       | connect and read timeouts for HTTP request device
| device.allow_redirects          | boolean | no       | enables or disables HTTP redirection
| device.proxies                  | object  | no       | proxies for HTTP request device
| device.verify                   | boolean | no       | enables or disables TLS certificate verification
| options                         | object  | yes      | additional options
| options.verbose                 | boolean | yes      | verbose

### Output Schema

The `ReturnStatus` job variable returned from the run automation `IAGDC: Check Device Connectivity` reports the success or failure of connecting the device on IAG. 

Example output of a successfully connected Ansible device:
```json
"ReturnStatus": {
  "details": [
    {
      "inventory_type": "ansible",
      "device": "Junos",
      "status": "SUCCESS",
      "message": "Connected device",
      "errors": [],
      "response": {
        "connectivity_response": {
          "response": "true"
        }
      }
    }
  ],
  "number_success": 1,
  "number_failure": 0,
  "message": "1 devices successfully connected on IAG, 0 devices failed to connect on IAG",
  "status": "SUCCESS"
  }
```

Example output of a failed connection for an Ansible device:
```json
"ReturnStatus": {
    "details": [
      {
        "inventory_type": "ansible",
        "device": "testDevice",
        "status": "FAILED",
        "message": "Unable to connect to device",
        "errors": [
          {
            "error_details": "",
            "message": "Unable to connect to device"
          }
        ],
        "response": {
          "connectivity_response": {
            "response": "false"
          }
        }
      }
    ],
    "number_success": 0,
    "number_failure": 1,
    "message": "0 devices successfully connected on IAG, 1 devices failed to connect on IAG",
    "status": "FAILED"
  }
```

Example output of a failed connection for an Ansible device (due to invalid device):
```json
"ReturnStatus": {
    "details": [
      {
        "inventory_type": "ansible",
        "device": "adsfsdf",
        "status": "FAILED",
        "message": "Unable to connect to device",
        "errors": [
          {
            "error_details": {
              "icode": "AD.500",
              "IAPerror": {
                "origin": "IAG-2021.2-connectorRest-handleEndResponse",
                "displayString": "Error 404 received on request",
                "recommendation": "Verify the request is accurate via debug logs and postman",
                "code": 404,
                "raw_response": {
                  "status": "success",
                  "code": 404,
                  "headers": {
                    "server": "gunicorn/20.0.4",
                    "date": "Mon, 06 Feb 2023 17:02:17 GMT",
                    "connection": "close",
                    "content-type": "application/json;",
                    "content-length": "73",
                    "last-modified": "2023-02-06 12:02:17.239039",
                    "cache-control": "no-store, no-cache, must-revalidate, post-check=0, pre-check=0, max-age=0",
                    "pragma": "no-cache",
                    "expires": "-1",
                    "x-frame-options": "DENY",
                    "x-xss-protection": "1",
                    "x-content-type-options": "nosniff"
                  },
                  "response": "{\"code\": 404, \"status\": 404, \"message\": \"Unable to locate host: adsfsdf\"}",
                  "redirects": 0,
                  "tripTime": "72ms",
                  "reqHdr": {
                    "Content-Type": "application/json",
                    "Accept": "application/json"
                  }
                }
              },
              "metrics": {
                "code": 404,
                "timeouts": 0,
                "redirects": 0,
                "retries": 0,
                "tripTime": 72,
                "isThrottling": false,
                "capabilityTime": "249ms"
              },
              "response": {
                "code": 404,
                "status": 404,
                "message": "Unable to locate host: adsfsdf"
              }
            },
            "message": "Unable to connect to device"
          }
        ],
        "response": {
          "connectivity_response": {
            "icode": "AD.500",
            "IAPerror": {
              "origin": "IAG-2021.2-connectorRest-handleEndResponse",
              "displayString": "Error 404 received on request",
              "recommendation": "Verify the request is accurate via debug logs and postman",
              "code": 404,
              "raw_response": {
                "status": "success",
                "code": 404,
                "headers": {
                  "server": "gunicorn/20.0.4",
                  "date": "Mon, 06 Feb 2023 17:02:17 GMT",
                  "connection": "close",
                  "content-type": "application/json;",
                  "content-length": "73",
                  "last-modified": "2023-02-06 12:02:17.239039",
                  "cache-control": "no-store, no-cache, must-revalidate, post-check=0, pre-check=0, max-age=0",
                  "pragma": "no-cache",
                  "expires": "-1",
                  "x-frame-options": "DENY",
                  "x-xss-protection": "1",
                  "x-content-type-options": "nosniff"
                },
                "response": "{\"code\": 404, \"status\": 404, \"message\": \"Unable to locate host: adsfsdf\"}",
                "redirects": 0,
                "tripTime": "72ms",
                "reqHdr": {
                  "Content-Type": "application/json",
                  "Accept": "application/json"
                }
              }
            },
            "metrics": {
              "code": 404,
              "timeouts": 0,
              "redirects": 0,
              "retries": 0,
              "tripTime": 72,
              "isThrottling": false,
              "capabilityTime": "249ms"
            },
            "response": {
              "code": 404,
              "status": 404,
              "message": "Unable to locate host: adsfsdf"
            }
          }
        }
      }
    ],
    "number_success": 0,
    "number_failure": 1,
    "message": "0 devices successfully connected on IAG, 1 devices failed to connect on IAG",
    "status": "FAILED"
  }
```

Example output of a successfully connected HTTP Request:
```json
"ReturnStatus": {
    "details": [
      {
        "inventory_type": "http_requests",
        "host": "bigip03-atl.local",
        "status": "SUCCESS",
        "message": "Connected device",
        "errors": [],
        "response": {
          "connectivity_response": {
            "status": 200,
            "time_elapsed": "0:00:00.022876",
            "response": "..."
          }
        }
      }
    ],
    "number_success": 1,
    "number_failure": 0,
    "message": "1 devices successfully connected on IAG, 0 devices failed to connect on IAG",
    "status": "SUCCESS"
  }
```

Example output of a failed connection to an HTTP Request:
```json
"ReturnStatus": {
    "details": [
      {
        "inventory_type": "http_requests",
        "host": "testDevice",
        "status": "FAILED",
        "message": "Unable to connect to device",
        "errors": [
          {
            "error_details": {
              "icode": "AD.500",
              "IAPerror": {
                "origin": "IAG-2021.2-connectorRest-handleEndResponse",
                "displayString": "Error 400 received on request",
                "recommendation": "Verify the request is accurate via debug logs and postman",
                "code": 400,
                "raw_response": {
                  "status": "success",
                  "code": 400,
                  "headers": {
                    "server": "gunicorn/20.0.4",
                    "date": "Mon, 06 Feb 2023 17:12:15 GMT",
                    "connection": "close",
                    "content-type": "application/json;",
                    "content-length": "366",
                    "last-modified": "2023-02-06 12:12:15.876040",
                    "cache-control": "no-store, no-cache, must-revalidate, post-check=0, pre-check=0, max-age=0",
                    "pragma": "no-cache",
                    "expires": "-1",
                    "x-frame-options": "DENY",
                    "x-xss-protection": "1",
                    "x-content-type-options": "nosniff"
                  },
                  "response": "{\"code\": 400, \"status\": 400, \"message\": \"Connection Error! Validate connection parameters and connectivity: HTTPConnectionPool(host='172.20.100.22', port=443): Max retries exceeded with url: /mgmt/mgmt (Caused by NewConnectionError('<urllib3.connection.HTTPConnection object at 0x7f18504f8370>: Failed to establish a new connection: [Errno 113] No route to host'))\"}",
                  "redirects": 0,
                  "tripTime": "3133ms",
                  "reqHdr": {
                    "Content-Type": "application/json",
                    "Accept": "application/json",
                    "Content-length": 68
                  }
                }
              },
              "metrics": {
                "code": 400,
                "timeouts": 0,
                "redirects": 0,
                "retries": 0,
                "tripTime": 3133,
                "isThrottling": false,
                "capabilityTime": "3313ms"
              },
              "response": {
                "code": 400,
                "status": 400,
                "message": "Connection Error! Validate connection parameters and connectivity: HTTPConnectionPool(host='172.20.100.22', port=443): Max retries exceeded with url: /mgmt/mgmt (Caused by NewConnectionError('<urllib3.connection.HTTPConnection object at 0x7f18504f8370>: Failed to establish a new connection: [Errno 113] No route to host'))"
              }
            },
            "message": "Unable to connect to device"
          }
        ],
        "response": {
          "connectivity_response": {
            "icode": "AD.500",
            "IAPerror": {
              "origin": "IAG-2021.2-connectorRest-handleEndResponse",
              "displayString": "Error 400 received on request",
              "recommendation": "Verify the request is accurate via debug logs and postman",
              "code": 400,
              "raw_response": {
                "status": "success",
                "code": 400,
                "headers": {
                  "server": "gunicorn/20.0.4",
                  "date": "Mon, 06 Feb 2023 17:12:15 GMT",
                  "connection": "close",
                  "content-type": "application/json;",
                  "content-length": "366",
                  "last-modified": "2023-02-06 12:12:15.876040",
                  "cache-control": "no-store, no-cache, must-revalidate, post-check=0, pre-check=0, max-age=0",
                  "pragma": "no-cache",
                  "expires": "-1",
                  "x-frame-options": "DENY",
                  "x-xss-protection": "1",
                  "x-content-type-options": "nosniff"
                },
                "response": "{\"code\": 400, \"status\": 400, \"message\": \"Connection Error! Validate connection parameters and connectivity: HTTPConnectionPool(host='172.20.100.22', port=443): Max retries exceeded with url: /mgmt/mgmt (Caused by NewConnectionError('<urllib3.connection.HTTPConnection object at 0x7f18504f8370>: Failed to establish a new connection: [Errno 113] No route to host'))\"}",
                "redirects": 0,
                "tripTime": "3133ms",
                "reqHdr": {
                  "Content-Type": "application/json",
                  "Accept": "application/json",
                  "Content-length": 68
                }
              }
            },
            "metrics": {
              "code": 400,
              "timeouts": 0,
              "redirects": 0,
              "retries": 0,
              "tripTime": 3133,
              "isThrottling": false,
              "capabilityTime": "3313ms"
            },
            "response": {
              "code": 400,
              "status": 400,
              "message": "Connection Error! Validate connection parameters and connectivity: HTTPConnectionPool(host='172.20.100.22', port=443): Max retries exceeded with url: /mgmt/mgmt (Caused by NewConnectionError('<urllib3.connection.HTTPConnection object at 0x7f18504f8370>: Failed to establish a new connection: [Errno 113] No route to host'))"
            }
          }
        }
      }
    ],
    "number_success": 0,
    "number_failure": 1,
    "message": "0 devices successfully connected on IAG, 1 devices failed to connect on IAG",
    "status": "FAILED"
  }
```

Example output of a failed connection to an HTTP Request (due to invalid inventory type):
```json
"ReturnStatus": {
    "details": [
      {
        "inventory_type": "sdfsdf",
        "host": "bigip03-atl.local",
        "status": "FAILED",
        "message": "Unable to connect to device",
        "errors": [
          {
            "error_details": "",
            "message": "Unable to connect to device"
          }
        ],
        "response": {
          "connectivity_response": "Invalid inventory type"
        }
      }
    ],
    "number_success": 0,
    "number_failure": 1,
    "message": "0 devices successfully connected on IAG, 1 devices failed to connect on IAG",
    "status": "FAILED"
  }
```

The following table details the property keys of the `ReturnStatus` object.

| key                                          | type   | description |
|--------------------------------------------- |--------|-------------|
| ReturnStatus                                 | object | job variable
| ReturnStatus.details                         | array  | overall details for devices
| ReturnStatus.details.inventory_type          | string | inventory type of device
| ReturnStatus.details.device or ReturnStatus.details.host   | string | name or host of Ansible device or HTTP Request, respectively
| ReturnStatus.details.status                  | string | failed or success status for individual device
| ReturnStatus.details.message                 | string | message of if device was able to connect or not
| ReturnStatus.details.errors                  | array  | error array if errors occur
| ReturnStatus.details.response                | object | response from IAG
| ReturnStatus.details.response.connectivity_response        | object | connectivity response from IAG
| ReturnStatus.number_success                  | integer| number of overall successful devices
| ReturnStatus.number_failure                  | integer| number of overall failed devices
| ReturnStatus.message                         | string | overall message for number of devices that were able to connect or not
| ReturnStatus.status                          | string | failed or success status of overall devices

## Additional Information

Please use your Itential Customer Success account if you need support when using this pre-built.