npm package: @itentialopensource/banner-management
Description: Banner management on network devices via Itential Automation Platform (IAP)
Author: Itential Artifacts
Latest version: 0.5.7-2023.1.0

# Banner Management

The Banner Management pre-built demonstrates the ability to agnostically manage different types of banners across multiple device types via Itential Automation Platform (IAP).

<!-- ![workflow shot](./img/banner-flow.png) -->
<table><tr><td>
	<img src="./img/banner-flow.png" alt="workflow shot" width="800px">
</td></tr></table>

This pre-built allows users to execute the automation against their network devices that are managed by Ansible. Currently, the supported device OS types are Cisco-IOS, Cisco-IOSXR & Cisco-NX.

This pre-built utilizes an Itential provided Ansible Role **"itential_set_banner"** which allows device level abstraction when configuring banners on selected device types.

## Installation Prerequisites
Users must satisfy the following prerequisites:
<!-- Include any other required apps or adapters in this list -->
<!-- Ex.: EC2 Adapter -->
* Itential Automation Platform
 * `^2021.2`

## Requirements

In order to take full advantage of the Banner Management pre-built automation, users will need to satisfy the following requirements:

1. Verify Itential Ansible Manager is successfully installed and functional.
2. Connectivity has been established between Itential Automation Platform and Ansible Manager Instance
3. Devices are onboarded within Ansible Manager and device connectivity has been established.
4. Itential provided Ansible Role: **itential_get_facts** + **itential_set_banner** has been onboarded into Ansible Manager and decorated with appropriate metadata. (How to onboard ansible roles & decorate them)

## How to Onboard & Decorate an Ansible Role within Itential Ansible Manager

**Perform the procedure below for both "itential_get_facts" & "itential_set_banner" roles.

[Download 'itential_get_facts' Role](./lib/itential_get_facts.tar.gz)

[Download 'itential_set_banner' Role](./lib/itential_set_banner.tar.gz)

1. Download and transfer the Itential provided Ansible Role: **itential_set_banner** to the VM where Itential Ansible Manager is installed.
2. Un-tar or Unzip the **itential_set_banner** tar file and move it to **/usr/share/ansible/roles**
3. Log into the Ansible Manager GUI and browse to the API Documentation Page and execute the /roles/refresh API located under the Roles section (As shown in the figure below)

  <!-- ![role-refresh](./img/role-refresh.png) -->
  <table><tr><td>
    <img src="./img/role-refresh.png" alt="role-refresh" width="800px">
  </td></tr></table>

5. Browse to the Roles section on the left side panel and verify the newly onboarded role can be seen.
6. Click on the **itential_set_banner** role and click the Edit button on the window in order to decorate the role with the appropriate metadata.
7. Copy the content available within the following file: **/usr/share/ansible/roles/itential_set_banner/metadata/decoration.json** and paste it in the text section (As shown in the figure below) and click the **SAVE** button.

  <!-- ![role-decorate](./img/role-decorate.png) -->
  <table><tr><td>
    <img src="./img/role-decorate.png" alt="role-decorate" width="800px">
  </td></tr></table>

8. At this point, you have successfully onboarded and decorated the **itential_set_banner** role. 
9. Log into the Itential Automation Platform and browse Adapter status page: Settings ---> Systems ---> Adapters (Tab) and restart the ansible manager adapter (As shown in the figure below)

  <!-- ![adapter-restart](./img/adapter-restart.png) -->
  <table><tr><td>
    <img src="./img/adapter-restart.png" alt="adapter-restart" width="800px">
  </td></tr></table>

10. Once the Ansible Manager adapter restarts successfully, the system would have auto-generated a network intelligent task that represents the newly onboarded Ansible role.

## 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. 
* 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="./img/install.png" alt="install" width="600px">
</td></tr></table>
<!-- REPLACE ABOVE WITH IMAGE OF YOUR PUBLISHED PRE-BUILT -->

## How to run

1. Browse to the Operations Manager application and run Operations Manager item called Banner Management (As shown in the figure below).

  <!-- ![automation-catalog-create](./img/create-ac.png) -->
  <table><tr><td>
    <img src="./img/operations-manager-item.png" alt="operations-manager-item" width="400px">
  </td></tr></table>

2. Click the "Run Manually" button in order to kick off the Banner Management automation (As shown in the figure above)
3. Fill in respective values into json-form as shown below (sample values only) and start the workflow.
<!-- ![banner-form](./img/banner-form.png) -->
  <table><tr><td>
    <img src="./img/banner-form.png" alt="banner-form" width="400px">
  </td></tr></table>

4. Once all the information has been submitted via the form, the system will continue executing the rest of the automated tasks and present a manual task in order to provide a Pre-Check/Post-Check Diff of the configuration change on the network device. Please review the configuration diff by executing the manual task (As shown in the figure below) and click the **"Proceed"** button to end the automation.

  <!-- ![banner-config-diff](./img/pre-post-diff.png) -->
  <table><tr><td>
    <img src="./img/pre-post-diff.png" alt="banner-config-diff" width="800px">
  </td></tr></table>

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