npm package: @itentialopensource/find-active-host
Description: Default artifact description
Author: Itential Artifacts
Latest version: 0.0.8-2023.1.0

<!-- This is a comment in md (Markdown) format, it will not be visible to the end user -->

<!-- Update the below line with your Pre-Built name -->
# Find Active Host

<!-- Leave TOC intact unless you've added or removed headers -->
## Table of Contents

* [Overview](#overview)
* [Installation Prerequisites](#installation-prerequisites)
* [Requirements](#requirements)
* [Features](#features)
* [Future Enhancements](#future-enhancements)
* [How to Install](#how-to-install)
* [How to Run](#how-to-run)
* [Additional Information](#additional-information)

## Overview

The Find Active Host pre-build enables users of Itential Automation Platform to identify hosts in which a device status is online.
<!-- Write a few sentences about the Pre-Built and explain the use case(s) -->
<!-- Avoid using the word Artifact. Please use Pre-Built, Pre-Built Transformation or Pre-Built Automation -->
<!-- Ex.: The Migration Wizard enables IAP users to conveniently move their automation use cases between different IAP environments -->
<!-- (e.g. from Dev to Pre-Production or from Lab to Production). -->

<!-- Workflow(s) Image Placeholder - TO BE ADDED DIRECTLY TO GitLab -->
<!-- REPLACE COMMENT BELOW WITH IMAGE OF YOUR MAIN WORKFLOW -->

<table><tr><td>
  <img src="./images/workflow.png" alt="workflow" width="800px">
</td></tr></table>

<!-- REPLACE COMMENT ABOVE WITH IMAGE OF YOUR MAIN WORKFLOW -->

<!-- ADD ESTIMATED RUN TIME HERE -->
<!-- e.g. Estimated Run Time: 34 min. -->
_Estimated Run Time_: 1 min

## Installation Prerequisites

Users must satisfy the following pre-requisites:

<!-- Include any other required apps or adapters in this list -->
<!-- Ex.: EC2 Adapter -->
* Itential Automation Platform
  * `^2023.1`

## Requirements

This Pre-Built requires the following:

<!-- Unordered list highlighting the requirements of the Pre-Built -->
<!-- EXAMPLE -->

<!-- * Ansible or NSO (with F5 NED) * -->
* NSO Adapter

  or

* Automation Gateway Adapter


## Features

The main benefits and features of the Pre-Built are outlined below.

<ul>
  <li>Provides a workflow that allows users to identify hosts and their status </li>
  <li>Provides users the optional ability to filter by host type (NSO or IAG)</li>
  <li>Provides users a random host name where the device is online, if there is one</li>
</ul> 
<!-- Unordered list highlighting the most exciting features of the Pre-Built -->
<!-- EXAMPLE -->
<!-- * Automatically checks for device type -->
<!-- * Displays dry-run to user (asking for confirmation) prior to pushing config to the device -->
<!-- * Verifies downloaded file integrity (using md5), will try to download again if failed -->


## How to Install

To install the Pre-Built:

* Verify you are running a supported version of the Itential Automation Platform (IAP) as listed above in the [Requirements](#requirements) section in order to install the Pre-Built. 
* The Pre-Built can be installed from within App-Admin_Essential. Simply search for the name of your desired Pre-Built and click the install button (as shown below).

<!-- REPLACE BELOW WITH IMAGE OF YOUR PUBLISHED PRE-BUILT -->

<table><tr><td>
  <img src="./images/install.png" alt="install" width="600px">
</td></tr></table>

<!-- REPLACE ABOVE WITH IMAGE OF YOUR PUBLISHED PRE-BUILT -->

<!-- OPTIONAL - Explain if external components are required outside of IAP -->
<!-- Ex.: The Ansible roles required for this Pre-Built can be found in the repository located at https://gitlab.com/itentialopensource/pre-built-automations/hello-world -->

## How to Run

Use the following to run the Pre-Built:

Child Job 

1. From the workflow canvas, select childJob task from the WorkFlowEngine. 
2. Search for and select "Find Active Host" in the worflow field.
3. Input the formData and click save.

example input:

"formData": {<br>
"nso": true,  //optional<br>
"iag": false, //optional<br>
"selectDevice": "device1"<br>
}

or

Operations Manager
1. This pre-built may be manually run from Operations Manager by selecting the "Find Active Host" from the automations menu and selecting run, and choosing the existing manual trigger. 
2. Fill out the form by providing an optional job description, selection a device from the drop down menu, and check the boxes NSO or IAG to filter by device type. 
3. Then click run to start the Find Active Host job.

<!-- Explain the main entrypoint(s) for this Pre-Built: Automation Catalog item, Workflow, Postman, etc. -->

## Additional Information

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