@itentialopensource/iagudd-update-device-details v0.1.4-2023.1.0

IAG Update Device Details

Table of Contents

• IAG Update Device Details
  • Table of Contents
  • Overview
  • Supported IAP Versions
  • Getting Started
    • Prerequisites
    • Capabilities
    • How to Install
    • Testing
  • Using this Pre-Built
    • Input Schema
    • Output Schema
  • Additional Information

Overview

The IAG Update Device Details pre-built is used to update the details for a list of IAG devices that are in the inventory of an IAG instance and returns their updated device details.

• 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
• A device in an IAG instance

Capabilities

• Gets the current details for the list of devices in IAG
• Updates details of multiple device types (Currently only supports HTTP Request and Ansible device types)
• Returns updated device details with authentication details removed

How to Install

To install this pre-built:

• Verify that you are running the documented prerequisites in order to install the pre-built.

• Follow the instructions on the Itential Documentation site for importing a pre-built.

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 a childJob task.

Note: The entry point workflow to this pre-built is called IAGUDD: Update Devices. Use this workflow name if running this pre-built in a childJob task.

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

Example input that has both Ansible and HTTP Request devices:

{
  "device": [
    {
      "device_name": "name",
      "inventory_type": "ansible",
      "iag_adapter_instance": "IAG",
      "onboarding": {
        "device-type": "network_cli",
        "ipaddress": "1.1.1.1",
        "port": "22",
        "ostype": "ios",
        "user": "user",
        "password": "password",
        "become": "true",
        "become_method": "enable",
        "become_pass": "become_pass"
      }
    },
    {
      "device_name": "name",
      "inventory_type": "http_requests",
      "iag_adapter_instance": "IAG",
      "onboarding": {
        "base_url": "1.1.1.1",
        "port": 443,
        "protocol": "http",
        "auth": {
          "username": "username",
          "password": "password"
        }
      }
    }
  ],
  "options": {
    "verbose": false
  }
}

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 | | device.inventory_type | string | yes | inventory type (ansible or http_requests) | | device.iag_adapter_instance | string | yes | adapter IAP instance
| device.onboarding | object | yes | user proposed update device details | options | object | yes | additional options | | options.verbose | boolean | yes | verbose |

Output Schema

The ReturnStatus job variable returned from the run pre-built workflow IAGUDD: Update Devices reports the success or failure of updating IAG device details for a device.

Example output for Ansible Devices (with one Ansible device erroring due to an invalid device name):

{
  "ReturnStatus": {
    "details": [
      {
        "status": "SUCCESS",
        "device": "device_name",
        "inventoryType": "ansible",
        "message": "Updated device",
        "errors": [],
        "response": {
          "update_device": {
              "device-type": "network_cli",
              "ipaddress": "1.1.1.2",
              "port": "22",
              "ostype": "ios",
              "become": "true",
              "become_method": "enable"
          },
          "get_device": {
            "name": "device_name",
            "device-type": "network_cli",
            "ipaddress": "1.1.1.1",
            "port": "443",
            "ostype": "cisco-ios",
            "become": "true",
            "become_method": "enable"
          }
        }
      },
      {
      "status": "FAILED",
      "device": "invalid_device_name",
      "inventory_type": "ansible",
      "message": "Unable to update device",
      "errors": [
        {
              "error_details": {
                "icode": "AD.500",
                "IAPerror": {
                  "origin": "IAG.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, 13 Jan 2023 19:28:23 GMT",
                      "connection": "close",
                      "content-type": "application/json;",
                      "content-length": "52",
                      "last-modified": "2023-01-13 14:28:23.714785",
                      "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": "63ms",
                    "reqHdr": {
                      "Content-Type": "application/json",
                      "Accept": "application/json",
                      "Authorization": ""
                    }
                  }
                },
                "metrics": {
                  "code": 404,
                  "timeouts": 0,
                  "redirects": 0,
                  "retries": 0,
                  "tripTime": 63,
                  "isThrottling": false,
                  "capabilityTime": "217ms"
                },
                "response": {
                  "code": 404,
                  "status": 404,
                  "message": "Not Found"
                }
              },
              "message": "Unable to update device"
        }      
      ],
        "response": {
          "update_device": {},
          "get_device": {
            "icode": "AD.500",
                          "IAPerror": {
                "origin": "IAG.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, 13 Jan 2023 19:28:23 GMT",
                    "connection": "close",
                    "content-type": "application/json;",
                    "content-length": "52",
                    "last-modified": "2023-01-13 14:28:23.714785",
                    "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": "63ms",
                  "reqHdr": {
                    "Content-Type": "application/json",
                    "Accept": "application/json"
                  }
                }
              },
              "metrics": {
                "code": 404,
                "timeouts": 0,
                "redirects": 0,
                "retries": 0,
                "tripTime": 63,
                "isThrottling": false,
                "capabilityTime": "217ms"
              },
              "response": {
                "code": 404,
                "status": 404,
                "message": "Not Found"
              }
            }
          }
        }
    ],
    "number_success": 1,
    "number_failure": 1,
    "message": "1 device successfuly updated on IAG, 1 device failed to update on IAG",
    "status": "FAILED" 
  }
}

Example output for HTTP Requests (with one device erroring due to an invalid inventory type):

{
  "ReturnStatus": {
    "details": [
      {
      "device": "device_name",
      "inventory_type": "http_requests",
      "status": "SUCCESS",
      "message": "Updated device",
      "errors": [],
        "response": {
          "update_device": {
              "base_url": "1.1.1.2",
              "port": 22,
              "protocol": "http"
          },
          "get_device": {
            "icode": "AD.200",
              "response": {
                "name": "device_name",
                "variables": {
                  "base_url": "1.1.1.1",
                  "port": 443,
                  "protocol": "http"
                }
              },
              "headers": {
                "server": "gunicorn/20.0.4",
                "date": "Fri, 13 Jan 2023 19:42:39 GMT",
                "connection": "close",
                "content-type": "application/json;",
                "content-length": "156",
                "last-modified": "2023-01-13 14:42:39.746778",
                "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": 68,
                "isThrottling": false,
                "capabilityTime": "243ms"
              }
            }
          }
        },
      {
        "status": "FAILED",
        "device": "device_name",
        "inventory_type": "invalid_inventory_type",
        "message": "Unable to update device",
        "errors": [
          {
              "error_details": "",
              "message": "Unable to update device"
          }
        ],
        "response": {
          "update_device": {},
          "get_device": "Invalid inventory type"
        }
      }
    ],
    "number_success": 1,
    "number_failure": 1,
    "message": "1 devices successfully updated on IAG, 1 devices failed to update to IAG",
    "status": "FAILED"
  }
}

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

Additional Information

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