2021.1 (latest)

Admin Essentials

On this page:

Prebuilts

Pre-builts allow developers to accelerate execution of network automation use cases within IAP (Itential Automation Platform). More specifically, pre-builts combine the abilities of multiple components that live within IAP. As such, a pre-built can be comprised of the following component types:

  • Automation Catalog
  • Automations (Operations Manager)
  • Form
  • JSON Forms
  • Command Template (MOP)
  • Analytic Template (MOP)
  • Golden Configs
  • Service Catalog
  • Template
  • Transformation
  • Triggers (Operations Manager)
  • Workflow

Each of these components serves a specific role to help various network use cases. You can read more about each component in their respective documentation guides on docs.itential.com.

Terminology

The following terms apply to the use of pre-builts in Admin Essentials.

Term Description
Pre-built A pre-built automation uses other IAP components to execute a certain network use case.
Component A component is a building block of a pre-built. Each component helps serve as a tool in a network automation use case.
IAP Dependency An IAP dependency is an application or adapter that is required by the pre-built to be in the current IAP environment for the pre-built to function properly. Note: Any dependency-check within the UI is strictly looking for the existence of the dependency.

Pre-builts UI

The primary user interfaces (UI) in the Pre-builts application are described below. Each interface allows you to view details about the pre-built along with the ability to uninstall a pre-built item or download data.

Details View

User interactions available through the Details View are shown below.

Figure 1: Pre-builts Details View

Details View

Label UI Element Edit View Function
1 Browse Click to browse all available pre-builts from the Itential Open Source Repository.
2 Search bar Use to search the list of installed pre-builts.
3 Installed pre-builts A collection list of all installed pre-builts on the current IAP environment.
4 Name The name of the pre-built.
5 Details Pre-built metadata regarding the publisher, publish date, version info, repository location, and license info.
6 Beta release A pre-built will show the Beta flag if the version is less than 1.0.0.
7 Uninstall Click to uninstall the pre-built.
8 Download Click to download a pre-built data file from the database of the current IAP environment.
9 ReadMe Displays the readme file for the pre-built.
10 Pre-Built Content Click the links to access components for the pre-built in Automation Catalog, JSON Forms, and Automation Studio.

Browse View

User interactions available through the Browse View are shown below.

Figure 2: Pre-builts Catalog Browse View

Browse View

Label UI Element List View Function
1 Search Used to search the pre-built repository.
2 Name The name of the pre-built.
3 Version Info The latest version of the pre-built that is compatible with the current running IAP version.
4 Description A summary description of the pre-built.
5 View Click to view details about the pre-built.
6 Beta release A pre-built will show the Beta flag if the version is less than 1.0.0. See note below for more information on this feature.
7 Download Click to download a pre-built data file from the repository.
8 Metadata Pre-built metadata regarding the publisher, publish date, version, repository type, and license type.
9 ReadMe The readme file for the pre-built.


Note: If the Beta release of a pre-built is not compatible with the current environment, a red indicator displays next to the Beta flag.

Figure 3: Non-Compatible Beta Release

Beta Noncompatible

Installing a Pre-built

To install a Pre-built:

  1. Open Admin Essentials from the Home page or the Applications menu.
  2. Select the Pre-builts dropdown in the sidebar (left-side of the screen).
  3. Click Browse.
  4. A list of available pre-builts will populate on the left-side of the screen.
  5. Select any pre-built and click Install.
  6. If the pre-built contains components that already exist on your system, you will be prompted to overwrite that content or cancel without overwriting.

If you are installing your first pre-built:

  1. After installing the pre-built, go to Authorization -> Groups.
  2. Click View List.
  3. Select Show Inactive.
  4. The Itential Pre-builts group should appear. Click Edit Group under Actions.
  5. Uncheck Inactive and click Save.
  6. In the sidebar, select Users
  7. Click the user you wish to apply the Itential Pre-built group to.
  8. Click Groups (on the Main view of the page).
  9. Select Itential Pre-builts and click Save.

Uninstalling a Pre-built

To uninstall a pre-built:

  1. Open Admin Essentials from the Home page or the Applications menu.
  2. Select the Pre-builts dropdown in the sidebar (left-side of the screen).
  3. Click the appropriate Pre-built repository (e.g. @itentialopensource) dropdown in the sidebar (left-side of the screen).
  4. A list of installed pre-builts will display.
  5. Select the pre-built you wish to uninstall.
  6. On the Details View for the pre-built you have selected, click Uninstall.

Downloading a Pre-built

There are two options for downloading a pre-built data file that can then be imported into an IAP environment. The first option downloads the content directly from the Itential pre-built repository whereas the second option provides the download from your locally installed system.

Download from Browse View

Downloading a pre-built from the Browse View will pull the data of the selected pre-built from its respective Gitlab repository.

  1. Open Admin Essentials from the Home page or the Applications menu.
  2. Select the Pre-builts dropdown in the sidebar (left-side of the screen).
  3. Click Browse.
  4. A list of available pre-builts will populate on the left-side of the screen.
  5. Each pre-built has the option to Download (bottom-right corner of the pre-built card).
  6. Click Download.

Download from Details View

Downloading a pre-built from the Pre-built Details View will pull the data of the selected pre-built from the IAP environment's database (e.g. the installed copy of the pre-built).

  1. Open Admin Essentials from the Home page or the Applications menu.
  2. Select the Pre-builts dropdown in the sidebar (left-side of the screen).
  3. Click the appropriate Pre-built repository (e.g. @itentialopensource) dropdown in the sidebar (left-side of the screen).
  4. A list of installed pre-builts will display.
  5. Select the pre-built you wish to download.
  6. On the Details View for the pre-built you have selected, click Download.

Importing a Pre-built

To import a pre-built:

  1. Open Admin Essentials from the Home page or the Applications menu.
  2. Click the Import icon.
  3. A modal window with appear with the option to Browse for files.
  4. Select the pre-built data file you wish to import.
  5. If the pre-built contains components that already exist on your system, you will be prompted to overwrite that content or cancel without overwriting.
  6. Click Import.

Figure 4: Overwrite Existing Components

Overwrite Checkbox

Updating a Pre-built

To update a pre-built:

  1. Open Admin Essentials from the Home page or the Applications menu.
  2. Select the Pre-builts dropdown in the sidebar (left-side of the screen).
  3. Click the appropriate Pre-built repository (e.g. @itentialopensource) dropdown in the sidebar (left-side of the screen).
  4. A list of installed pre-builts will display.
  5. If a pre-built is available for an update, an orange dot will appear next to the pre-built name.
  6. Click the pre-built that is available for an update.
  7. Click Update.
  8. A similiar dialog will appear confirming you are aware of the actions you are about to take.

Pre-built Repository Configurations

Itential Automation Platform (IAP) supports the configuration of multiple Pre-built Automation repositories. This means that a user can provide configurations to fetch Pre-built Automations from multiple repository locations as well as install and manage those Pre-built Automations in a single IAP environment.

This guide defines the minimum requirements and process to have functioning multi-repository configurations in Itential Automation Platform. Instructions on how to create, manage, and delete these Pre-built-Automation repository configurations are also provided.

Pre-built Automation Repository Configuration Properties

The configuration properties for the @itentialopensource Pre-built Automation repository are configured by default on startup of IAP.

The following properties are required for a Pre-built Automation repository configuration.

Property Description
enabled A flag that denotes if the repository configuration is connected or disconnected.
versionStatus Specified as current or latest. Rendered as "Show all Versions" in the configuration, this flag denotes if the content of the repository will show older prebuilts that might or might not be compatible with the local system. In other words, the prebuilts displayed by default match the version of the local system; however, when this property set to "latest", it will also show any prebuilts from older versions but only the most recent version.
type The type of repository configuration.
hostname The hostname or IP address of the repository server.
path The path for the repository server.
Hint: The path must be the part of the url after the https://hostname/.
credentials The necessary credentials needed to authorize access to a repository (e.g., required if accessing a private gitlab repository).
token The access token used to authorize access to a repository.


Repository Configuration

{
    ...
    "repoConfigs": {
        "@itentialopensource": {
            "enabled": true,
            "versionStatus": "current",
            "type": "gitlab",
            "hostname": "gitlab.com",
            "path": "itentialopensource/pre-built-automations",
            "credentials": {
                "token": "TOKEN STRING"
            }
        }
    }
    ...
}

Supported Repository Types

The type property of repoConfigs can only be set to the types supported within IAP such as the following:

Type Description
gitlab For use when the repository is within GitLab.

Managing Repository Configurations

The repository configurations can be managed from the Browse menu of the Pre-builts Automations section in Admin Essentials.

Figure 5: Browse Menu

Browse

In the Browse menu, a user can select from a dropdown the repository configuration that will be used to fetch Pre-built Automations. To the right of the dropdown list there is a menu button that allows a user to manage their repository configurations. In these options, a user has the ability to create, edit, or delete a configuration. In addition to these options, a user can also select to Manage repositories which will allow the user to view all of the repository configurations currently on the system.

Figure 6: Manage Repository Configurations

Manage

Add New Repository

A user can create a new repository configuration by going to the action menu in Browse Pre-built Automations and selecting Add a new repository. A dialog will appear, prompting the user to fill in the Configuration Properties.

A user can also create a new repository configuration without using the UI. An API request can be sent to POST /prebuilts-repository/configs with a request body of the following:

{
    "name": "test",
    "config": {
        "enabled": true,
        "versionStatus": "current",
        "type": "gitlab",
        "hostname": "gitlab.com",
        "path": "itentialopensource/pre-built-automations",
        "credentials": {}
    }
}

Edit a Repository

A user can edit an existing repository configuration by going to the action menu in Browse Pre-built Automations and selecting Edit repository details. A dialog will appear, prompting the user to modify each property that can be edited.

Connect or Disconnect a Configuration

A user can connect or disconnect an existing repository configuration by going to the action menu in Browse Pre-built Automations and selecting Edit repository details. A dialog will appear with all of the existing properties for the selected repository configuration. In the top right corner of the dialog there is a toggle that can be switched on/off which represents the repository configuration being connected or disconnected.

Note: If a repository configuration is disconnected, any associated Pre-built Automations installed on the system will no longer be able to receive any updates. Once the repository configurations is reconnected then the Pre-built Automations can resume receiving updates.

Delete a Configuration

A user can delete an existing repository configuration by going to the action menu in Browse Pre-built Automations and selecting Delete repository. A dialog will appear, prompting the user to select a repository configuration to delete.

Note: If a repository configuration is deleted from IAP and that configuration had associated Pre-built Automations that were installed on the system, each of those Pre-built Automations will be updated to a "local" configuration. This means the Pre-built Automations is no longer associated with a repository and will not be able to receive updates. Furthermore, if the repository is reconnected and the same Pre-built Automations are installed, they will conflict with the "local" Pre-builts and must be managed accordingly.

Viewing Installed Pre-builts from Different Repositories

Installed pre-builts from different repositories will appear under the Pre-builts tab in Admin Essentials. Each repository config will be listed as a collapsible menu, with the pre-builts from that config listed under it. Pre-builts from connected repositories will have update icons if they are out of sync; pre-builts from disconnected repositories will not check the repository for updates. In addition, pre-builts from deleted repositories will not check for updates (as the repository is no longer accessible), and will also be moved under a local namespace in the sidebar.

The dropdown menu within the Pre-builts Catalog also allows the user to choose which repository to query when getting a list of Pre-builts. This interface limits the query to only one repository at a time.