npm package: @itentialopensource/migration-wizard
Description: Migration Wizard allows users to bundle and migrate components from one environment to another. This automation will create an artifact and return a tarball the user can download.
Author: Itential Artifacts
Latest version: 0.0.1-2019.3.2

# Migration Wizard

## Table of Contents

* [Intro](#intro)
* [Requirements](#requirements)
* [Known Limitations](#known-limitations)
* [How to Install](#how-to-install)
* [How to Run](#how-to-run)
    * [Run with Automation Catalog](#run-with-automation-catalog)

## Intro
The Migration Wizard enables IAP users to conveniently move their automation use cases between their different IAP environments (e.g. from Dev to Pre-Production or from Lab to Production). This artifact will discover all components in IAP that are required to run an automation and bundles these components into a single exported .tgz file. This file can be imported on any other IAP server through app-artifacts without the need for an internet connection.

<table><tr><td>
  <img src="https://gitlab.com/itentialopensource/pre-built-automations/migration-wizard/raw/master/images/artifact_workflow.png" alt="artifact_workflow" width="800px">
</td></tr></table>

## Requirements
In order to use the Migration Wizard automation, users will have to satisfy the following pre-requisites:
* Itential Automation Platform
  * `^2019.2.4`
* App-Artifacts
  * `^2.6.2`

## Known Limitations
Migration Wizard does NOT currently discover service dependencies that are not default IAP services (apps or adapters). These services must be added manually when migrating between environments as the required service will NOT be a part of the user's bundled artifact.

## How to Install
Please ensure that you are running a supported version of Itential Automation Platform (IAP) as listed above in the [Pre-Requisites](#pre-requisites) section in order to install Migration Wizard. If you do not currently have App-Artifacts installed as a service on your node, the .tgz file or "tarball" can be obtained from the [Nexus repository](https://registry.aws.itential.com/#browse/browse:app-prebuilt_automations:2019.2). Please refer to the instructions included in the App-Artifacts README to install it.

Migration Wizard can be installed from within App-Artifacts. Simply search for `migration-wizard` and click the install button as shown below:

<table><tr><td>
  <img src="https://gitlab.com/itentialopensource/pre-built-automations/migration-wizard/raw/master/images/install.png" alt="install" width="800px">
</td></tr></table>

Alternatively, you may clone this repository and run `npm pack` to create a tarball which can then be installed via the offline installer in App-Artifacts. Please consult the documentation for App-Artifacts for further information.

## How to Run
### Input
To run the Migration Wizard artifact, the user can choose between two options. The first, is to start the artifact from Automation Catalog, which is done through the Itential Automation Platform (IAP) GUI. The second option is to make a HTTP Request to the server via Postman. Instructions on how to execute both options are listed below.

### Run with Automation Catalog

First, the user will need to access the artifact entry through _*Automation Catalog*_ as seen below.
<table><tr><td>
  <img src="https://gitlab.com/itentialopensource/pre-built-automations/migration-wizard/raw/master/images/home_screen.png" alt="automation_catalog" width="800px">
</td></tr></table>

From _*Automation Catalog*_, the user can select to start the automation by clicking the `run` option, which can be seen in the following image.
<table><tr><td>
  <img src="https://gitlab.com/itentialopensource/pre-built-automations/migration-wizard/raw/master/images/automation_run.png" alt="start" width="800px">
</td></tr></table>

After choosing to run the automation, the user will be promted for an Automation Catalog or Workflow to perform migration on.

<table><tr><td>
  <img src="https://gitlab.com/itentialopensource/pre-built-automations/migration-wizard/raw/master/images/json-form.png" alt="input" width="800px">
</td></tr></table>

After the user clicks the `Run` button, Migration Wizard will discover all dependencies required by the _*Automation Catalog*_ or _*Workflow*_ item, as well as version information for each IAP application required to install the bundled artifact. The results of the discovery will then be displayed to the user for them to confirm:

<table><tr><td>
  <img src="https://gitlab.com/itentialopensource/pre-built-automations/migration-wizard/raw/master/images/discovery.png" alt="discovery" width="400px">
</td></tr></table>

Migration Wizard will next prompt the user for metadata for the bundle, giving the user an opportunity to provide a short description and any keywords relevant to the artifact bundle. Once these two parameters are provided, the user will then be asked to complete a README template for their artifact bundle.

Once the metadata is collected, Migration Wizard will perform a health check to gather module information in order to properly bundle the artifact. Please note that this step will not be required to run in future versions of Migration Wizard. The user will be prompted to perform the health check as an admin user:

<table><tr><td>
  <img src="https://gitlab.com/itentialopensource/pre-built-automations/migration-wizard/raw/master/images/healthcheck.png" alt="health_check" width="700px">
</td></tr></table>

Migration Wizard will bundle all dependencies and create the required files needed to install the outputted tarball into a new environment. Upon success of this process, the user will be provided with the option to download their bundled artifact:

<table><tr><td>
  <img src="https://gitlab.com/itentialopensource/pre-built-automations/migration-wizard/raw/master/images/download.png" alt="health_check" width="700px">
</td></tr></table>

### Output
After the artifact has completed running the automation, the user will be presented with a .tgz file containing all of the necessary components required to run their initial Automation Catalog or Workflow.