npm package: @itentialopensource/iag-delete-device
Description: description
Author: Itential Artifacts
Latest version: 1.0.4-2023.1.0

# IAG Delete Device

## Table of Contents

- [IAG Delete Device](#iag-delete-device)
  - [Table of Contents](#table-of-contents)
  - [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 Delete Device** pre-built is used to delete a list of existing IAG devices that are in the inventory of an IAG instance and returns device information and deletion information.


_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.
  - `^2022.1.x`
- An instantiated IAP IAG adapter.

### Capabilities

- Performs an existence check of multiple devices types onboarded to IAG then deletes the devices that exist.
- **Note**: Currently only supports HTTP Requests and Ansible Device types

### How to Install

To install this pre-built:

- Verify that you are running the documented [prerequisites](#prerequisites) 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 or as a [childJob task](https://docs.itential.com/docs/childjob-1). 

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

Running this pre-built depends on providing the 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

Example input for an Ansible device:
```json
{
  "device": [
    {
      "device_name": "deviceName",
      "inventory_type": "ansible",
      "iag_adapter_instance": "IAG",
    }
  ],
  "options": {
    "verbose": true
  }
}
```
Example input for an HTTP Request:
```json
{
  "device": [
    {
      "device_name": "deviceName",
      "inventory_type": "http_requests",
      "iag_adapter_instance": "IAG",
    }
  ],
  "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  | yes     | device name for ansible device |
| device.inventory_type                     | string  | yes     | inventory type (ansible or http_requests) |
| device.iag_adapter_instance               | string  | yes     | adapter for IAP instance
| options                                   | object  | yes     | additional options
| options.verbose                           | boolean | yes     | verbose

### Output Schema
The `ReturnStatus` job variable returned from the run automation `IAGDD: Delete Device` or the run childJob task `IAGDD: Delete Devices` reports the success or failure of deleting the device on IAG. 

Example output of successfully deleted HTTP Request and Ansible device:
```json
"ReturnStatus": {
    "details": [
      {
        "device": "deleteHTTPRequest",
        "inventory_type": "http_requests",
        "status": "SUCCESS",
        "message": "Device successfully deleted",
        "errors": [],
        "response": {
          "device_details": {
            "icode": "AD.200",
            "response": {
              "name": "deleteHTTPRequest",
              "variables": {
                "base_url": "1.1.1.2:80",
                "protocol": "http"
              }
            },
            "headers": {
              "server": "gunicorn/20.0.4",
              "date": "Fri, 03 Mar 2023 17:52:56 GMT",
              "connection": "close",
              "content-type": "application/json;",
              "content-length": "145",
              "last-modified": "2023-03-03 12:52:56.674403",
              "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"
            },
            "metrics": {
              "code": 200,
              "timeouts": 0,
              "redirects": 0,
              "retries": 0,
              "tripTime": 65,
              "isThrottling": false,
              "capabilityTime": "225ms"
            }
          },
          "delete_details": {
            "icode": "AD.200",
            "response": "success",
            "headers": {
              "server": "gunicorn/20.0.4",
              "date": "Fri, 03 Mar 2023 17:52:57 GMT",
              "connection": "close",
              "content-type": "application/json;",
              "content-length": "50",
              "last-modified": "2023-03-03 12:52:57.275370",
              "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"
            },
            "metrics": {
              "code": 200,
              "timeouts": 0,
              "redirects": 0,
              "retries": 0,
              "tripTime": 59,
              "isThrottling": false,
              "capabilityTime": "194ms"
            }
          }
        }
      },
      {
        "device": "deleteAnsible",
        "inventory_type": "ansible",
        "status": "SUCCESS",
        "message": "Device successfully deleted",
        "errors": [],
        "response": {
          "device_details": {
            "name": "deleteAnsible",
            "device-type": "network_cli",
            "ipaddress": "1.1.1.1",
            "port": "80",
            "ostype": "cisco-ios",
            "become": "true",
            "become_method": "enable"
          },
          "delete_details": "success"
        }
      }
    ],
    "number_failure": 0,
    "number_success": 2,
    "message": "2 device(s) successfully deleted on IAG, 0 device(s) failed to delete on IAG",
    "status": "SUCCESS"
  }
```

Example output of failed deletions of HTTP Request and Ansible device due to invalid inventory type
```json
"ReturnStatus": {
    "details": [
      {
        "device": "deleteHTTPRequest",
        "inventory_type": "asdfdsfa",
        "status": "FAILED",
        "errors": [
          {
            "error_details": "",
            "message": "Unable to get device details"
          }
        ],
        "message": "Device deletion unsuccessful",
        "response": {
          "device_details": "Invalid inventory type",
          "delete_details": null
        }
      },
      {
        "device": "deleteAnsible",
        "inventory_type": "asdfdsaf",
        "status": "FAILED",
        "errors": [
          {
            "error_details": "",
            "message": "Unable to get device details"
          }
        ],
        "message": "Device deletion unsuccessful",
        "response": {
          "device_details": "Invalid inventory type",
          "delete_details": null
        }
      }
    ],
    "number_failure": 2,
    "number_success": 0,
    "message": "0 device(s) successfully deleted on IAG, 2 device(s) failed to delete on IAG",
    "status": "FAILED"
  }
```

Example output of nonexistent Ansible device and HTTP Request:
```json
"ReturnStatus": {
    "details": [
      {
        "device": "nonexistentAnsible",
        "inventory_type": "ansible",
        "status": "SUCCESS",
        "message": "Device successfully deleted",
        "errors": [],
        "response": {
          "device_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": "Fri, 03 Mar 2023 19:04:34 GMT",
                  "connection": "close",
                  "content-type": "application/json;",
                  "content-length": "52",
                  "last-modified": "2023-03-03 14:04:34.922562",
                  "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\": \"Not Found\"}",
                "redirects": 0,
                "tripTime": "53ms",
                "reqHdr": {
                  "Content-Type": "application/json",
                  "Accept": "application/json"
                }
              }
            },
            "metrics": {
              "code": 404,
              "timeouts": 0,
              "redirects": 0,
              "retries": 0,
              "tripTime": 53,
              "isThrottling": false,
              "capabilityTime": "200ms"
            },
            "response": {
              "code": 404,
              "status": 404,
              "message": "Not Found"
            }
          },
          "delete_details": null
        }
      },
      {
        "device": "nonexistentHTTPRequest",
        "inventory_type": "http_requests",
        "status": "SUCCESS",
        "message": "Device successfully deleted",
        "errors": [],
        "response": {
          "device_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": "Fri, 03 Mar 2023 19:04:35 GMT",
                  "connection": "close",
                  "content-type": "application/json;",
                  "content-length": "52",
                  "last-modified": "2023-03-03 14:04:35.823132",
                  "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\": \"Not Found\"}",
                "redirects": 0,
                "tripTime": "58ms",
                "reqHdr": {
                  "Content-Type": "application/json",
                  "Accept": "application/json"
                }
              }
            },
            "metrics": {
              "code": 404,
              "timeouts": 0,
              "redirects": 0,
              "retries": 0,
              "tripTime": 58,
              "isThrottling": false,
              "capabilityTime": "196ms"
            },
            "response": {
              "code": 404,
              "status": 404,
              "message": "Not Found"
            }
          },
          "delete_details": null
        }
      }
    ],
    "number_failure": 0,
    "number_success": 2,
    "message": "2 device(s) successfully deleted on IAG, 0 device(s) failed to delete on IAG",
    "status": "SUCCESS"
  }
```

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.device                  | string | name of Ansible device or HTTP Request
| ReturnStatus.details.inventory_type          | string | inventory type of device
| ReturnStatus.details.status                  | string | failed or success status for individual device   
| ReturnStatus.details.message                 | string | message of if device was able to be deleted or not
| ReturnStatus.details.errors                  | array  | error array if errors occur 
| ReturnStatus.details.response                | object | response from IAG
| ReturnStatus.details.response.device_details        | object | device details from existence check
| ReturnStatus.details.response.delete_details        | object | details of deleted device
| 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 be deleted 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.