Pre-Builts

Pre-Built Component Types

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

• Automation Catalog
• Automations (Operations Manager)
• Form
• JSON Forms
• Integrations
• Integration Models
• Command Template (MOP)
• Analytic Template (MOP)
• Service Catalog
• Template
• Transformation
• Triggers (Operations Manager)
• Workflow

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

Terminology

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

Pre-Builts UI

The main interfaces in the Prebuilts 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 referenced below.

Figure 1: Pre-builts Details View

Browse View

User interactions available through the Browse View are referenced below.

Figure 2: Browse Prebuilts Catalog

Figure 3: Noncompatible Beta Flag

Installing a Prebuilt

To install a pre-built:

1. Open Admin Essentials from the Home page or the Applications menu.
2. Select the Prebuilts dropdown in the sidebar (left-side of the screen).
3. Click Browse.
4. A list of available prebuilts will populate on the left-side of the screen.
5. Select any prebuilt and click Install.
6. If the prebuilt 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 prebuilt, go to Authorization → Groups.
2. Click View List.
3. Select Show Inactive.
4. The Itential Prebuilts 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 Prebuilt group to.
8. Click Groups (on the Main view of the page).
9. Select Itential Pre-builts and click Save.

Uninstalling a Prebuilt

To uninstall a pre-built:

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

Installing Pre-Builts Manually

This section outlines the steps to install Itential Pre-built automations manually when your Internet connection is down and not available from Itential Platform.

Download Artifact JSON File

1. Navigate to the Pre-builts collection at Itential Automation MarketPlace.
2. Use the slider to filter by Automation.
3. Select the desired pre-built automation to display a description, technical details and other related information.
4. From the pre-built, click View Repository in the left navigation menu to be redirected to where the pre-built is located in the Itential Opensource repository. For demonstration purposes, Netbox IP Address Management was randomly selected (Figure 2) as an example.

Figure 4: Itential Automation Marketplace

 

Figure 5: Itential Pre-Built (Example)

 

5. From the pre-built in the repository, click the artifact.json to open the file.
6. Click the download icon to save the file to your local drive.

Figure 6: Itential Opensource Repository (Example artifact.json file)

 

Figure 7: Download File (Example)

Import into Admin Essentials

1. Navigate to Admin Essentials within Itential Platform and click the import icon in the top toolbar to open the Import dialog.

   Figure 8: Admin Essentials
   

2. Select "Pre-built" in the dropdown list to open the Import modal.

   Figure 9: Import Dialog
   

3. Select "click to browse" and navigate to the artifact.json file saved to your local drive.

   Figure 10: Browse File System
   

4. Select the artifact.json file you downloaded. A preview of the pre-built ReadMe will display.

    Note: There may be additional dependencies that are required. The ReadMe file for the pre-built will explain if there are additional prerequisites or requirements for the install.

5. Click the Import button to install the pre-built and its associated artifacts. Once the pre-built is installed, it will be loaded into Itential Platform.

Figure 11: Pre-Built ReadMe

Troubleshooting

If Itential Platform determines a dependency is not installed, you will see a warning banner and most likely will not be allowed to install the pre-built until the prerequisite is satisfied.

Figure 12: Warning Banner

If you experience any issues with an Itential Pre-built, please contact the Pre-builts Team by opening a service desk ticket using the Customer Portal.

Downloading Pre-Builts

There are two options for downloading a prebuilt data file that can then be imported into an Itential Platform 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 Prebuilts 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 Itential Platform 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 prebuilt you have selected, click Download.

Importing Pre-Builts

To import a pre-built:

1. Open Admin Essentials from the Home page or the Applications menu.
2. Click the Import icon and then select Pre-built from the list.
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 file contains components that already exist on your system, you will be prompted to overwrite that content or cancel without overwriting.
6. Click Import.

Figure 13: Overwrite Existing Prebuilt Components

Updating Pre-Builts

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 prebuilts will display.
5. If a pre-built is available for an update, an orange dot will appear next to the prebuilt 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 Automation Repository

The minimum requirements and process to have a functioning Pre-built Automation repository are defined below. Once configured properly, Admin Essentials is able to query the repository and incorporate and manage users' custom Pre-built Automations.

Itential Platform now supports the configuration of custom and multiple Pre-built Automation repositories. This means that users can provide a configuration to fetch Pre-built Automations from their custom Pre-built Automation repository as opposed to previous releases where it was only allowed to pull from Itential's official Pre-built Automation open-source library.

The following conventions must be followed in order for Admin Essentials to properly integrate with the custom Pre-Built Automation Repository.

Repository Structure

The Pre-built Automation Repository must be in GitLab. Each Pre-built Automation is its own GitLab repository. The structure of the repository is outlined in the sections below.

The branching strategy within each GitLab repository can be customized to whatever convention you want for development purposes; however, in order to properly appear in Admin Essentials, each Pre-built Automation must follow a specific branch naming convention that is considered as the release branches.

Versioning Requirements

Most Itential Platform releases follow a version convention like the one below:

x.y.z-2023.1.m

The "2023.1" equates to the major release of Itential Platform and the "m" is the maintenance release.

In order for a Pre-built Automation to be consumed by an Itential Platform environment with the above version, the Pre-built Automation must also have that same versioning structure in the package.json file.

For example, the version of the Pre-built Automation would have the traditional major.minor.patch with Semantic Versioning then a dash ("-") followed by the corresponding major release of Itential Platform (YYYY.Z) the Pre-built Automation supports and lastly, each change to the prebuilt would increment the maintenance number (the "m" in the example above).

Branch Naming Requirement

The Pre-built Automation also must be tied to a specific release by creating a branch in the repository named with release/YYYY.Z. This versioning scheme is accomplished by having different Git branches to reflect the different release versions.

For example, if we have a custom Pre-built Automation the repository branches would be:

* master
* release/2021.1 -> consumable by IAP release/2021.1
* release/2020.2 -> consumable by IAP release/2020.2
* release/2020.1 -> consumable by IAP release/2020.1

Structure of a Pre-Built Automation

The structure of the Pre-built Automation must be strictly followed for the Admin Essentials UI to properly process and display the custom Pre-built Automations. Following the conventions below will ensure the best user experience.

Each Pre-built Automation must include the following directories and files to be consumable by Itential Platform:

/bundles/
README.md
manifest.json
package.json
artifact.json

bundles

The bundles directory consists of a directory map of all the Itential Platform component files contained within the Pre-built Automation. An example directory structure for a Pre-built Automation that contains one of each component (two transformations) supported in Pre-built Automations would be the following:

/bundles
|--> /ac_-_agenda_job
    |--> automation-catalog-1.json
|--> /forms
    |--> form-1.json
|--> /golden_config
    |--> golden-config-1.json
|--> /json_forms
    |--> json-forms.json
|--> /mop_template
    |--> mop-template-1.json
|--> /mop_analytic_template
    |--> mop-analytic-template-1.json
|--> /service_catalog
    |--> service-catalog-1.json
|--> /template
    |--> template-1.json
|--> /transformation
    |--> transformation-1.json
    |--> transformation-2.json
|--> /workflow
    |--> workflow.json

The JSON files under each sub-directory contain the data for that component type. These files are the exports from an Itential Platform environment.

README.md

Every Pre-built Automation is required to have a README.md file. This is important to describe the contents and use-cases of the Pre-built Automation and will be displayed on the Admin Essentials Browse page as well as when browsing a Pre-built Automation's Details.

manifest.json

The manifest.json file is a map of all components contained within the Pre-built Automation. This file informs Itential Platform of the content contained in the Pre-built Automation along with the name, type, and location of each component in the bundle.

{
    "bundleName": "Custom Pre-built Automation",
    "artifacts": [
      {
        "id": "Automation Catalog Name 1",
        "name": "Automation Catalog Name 1",
        "type": "ac-agenda-job",
        "location": "/bundles/ac_agenda_jobs/automation-catalog-1.json"
      },
      {
        "id": "Form Name 1",
        "name": "Form Name 1",
        "type": "forms",
        "location": "/bundles/forms/form-1.json"
      },
      {
        "id": "Golden Config Name 1",
        "name": "Golden Config Name 1",
        "type": "golden-config",
        "location": "/bundles/golden-config/golden-config-1.json"
      },
      {
        "id": "Json Form Name 1",
        "name": "Json Form Name 1",
        "type": "json-forms",
        "location": "/bundles/json_forms/json-forms.json"
      },
      {
        "id": "MOP Template 1",
        "name": "MOP Template 1",
        "type": "mop-template",
        "location": "/bundles/mop_template/mop-template-1.json"
      },
      {
        "id": "MOP Analytic Template 1",
        "name": "MOP Analytic Template 1",
        "type": "mop-analytic-template",
        "location": "/bundles/mop_analytic_template/mop-analytic-template-1.json"
      },
      {
        "id": "Service Catalog 1",
        "name": "Service Catalog 1",
        "type": "service-catalog",
        "location": "/bundles/service_catalog/service_catalog-1.json"
      },
      {
        "id": "Template 1",
        "name": "Template 1",
        "type": "template",
        "location": "/bundles/template/template-1.json"
      },
      {
        "id": "Transformation 1",
        "name": "Transformation 1",
        "type": "transformation",
        "location": "/bundles/transformation/transformation-1.json"
      },
      {
        "id": "Workflow Name",
        "name": "Workflow Name",
        "type": "workflow",
        "location": "/bundles/workflow/workflow.json"
      }
    ]
}

package.json

The package.json file is similar to the conventions set by npm.

{
  "name": "Custom Pre-built Automation",
  "version": "1.0.0-2021.1.1",
  "description": "A description of the Pre-built Automation",
  "author": "John Doe",
  "license": "Apache-2.0",
  "repository": {
    "type": "gitlab",
    "hostname": "gitlab.com",
    "path": "/path/to/my/prebuilts-repo"
  },
  "IAPDependencies": {
    "@itential/app-automation_catalog": "2.5.4",
    "@itential/app-json_forms": "1.13.5",
    "@itential/app-workflow_engine": "6.7.10"
  }
}

artifact.json

The artifact.json file is the most important aspect of the Pre-built Automation. This file is a combination of all the files mentioned above, containing all the information needed to consume a Pre-built Automation into an Itential Platform environment.

Close inspection reveals that the <metadata> property contains the package.json; <manifest> contains the manifest.json; and <bundles> is the concatenation of each of the files under the /bundles directory.

{
  "metadata": {
    "name": "Custom Pre-built Automation",
    "version": "1.0.0-2021.1.1",
    "description": "A description of the Pre-built Automation",
    "author": "John Doe",
    "license": "Apache-2.0",
    "repository": {
      "type": "gitlab",
      "hostname": "gitlab.com",
      "path": "/path/to/my/prebuilts-repo"
    },
     "IAPDependencies": {
      "@itential/app-automation_catalog": "2.5.4",
      "@itential/app-json_forms": "1.13.5",
      "@itential/app-workflow_engine": "6.7.10"
    }
  },
  "manifest": {
    "bundleName": "Custom Pre-built Automation",
    "artifacts": [
      {
        "id": "Automation Catalog Name 1",
        "name": "Automation Catalog Name 1",
        "type": "ac-agenda-job",
        "location": "/bundles/ac_agenda_jobs/automation-catalog-1.json"
      },
      {
        "id": "Form Name 1",
        "name": "Form Name 1",
        "type": "forms",
        "location": "/bundles/forms/form-1.json"
      },
      {
        "id": "Golden Config Name 1",
        "name": "Golden Config Name 1",
        "type": "golden-config",
        "location": "/bundles/golden-config/golden-config-1.json"
      },
      {
        "id": "Json Form Name 1",
        "name": "Json Form Name 1",
        "type": "json-forms",
        "location": "/bundles/json_forms/json-forms.json"
      },
      {
        "id": "MOP Template 1",
        "name": "MOP Template 1",
        "type": "mop-template",
        "location": "/bundles/mop_template/mop-template-1.json"
      },
      {
        "id": "MOP Analytic Template 1",
        "name": "MOP Analytic Template 1",
        "type": "mop-analytic-template",
        "location": "/bundles/mop_analytic_template/mop-analytic-template-1.json"
      },
      {
        "id": "Service Catalog 1",
        "name": "Service Catalog 1",
        "type": "service-catalog",
        "location": "/bundles/service_catalog/service_catalog-1.json"
      },
      {
        "id": "Template 1",
        "name": "Template 1",
        "type": "template",
        "location": "/bundles/template/template-1.json"
      },
      {
        "id": "Transformation 1",
        "name": "Transformation 1",
        "type": "transformation",
        "location": "/bundles/transformation/transformation-1.json"
      },
      {
        "id": "Workflow Name",
        "name": "Workflow Name",
        "type": "workflow",
        "location": "/bundles/workflow/workflow.json"
      }
    ]
  },
  "bundles": [
    {
      "type": "ac-agenda-job",
      "data": { ... }
    },
    {
      "type": "forms",
      "data": { ... }
    },
    {
      "type": "golden-config",
      "data": { ... }
    },
    {
      "type": "json-form",
      "data": { ... }
    },
    {
      "type": "mop-template",
      "data": { ... }
    },
    {
      "type": "mop-analytic-template",
      "data": { ... }
    },
    {
      "type": "service-catalog",
      "data": { ... }
    },
    {
      "type": "template",
      "data": { ... }
    },
    {
      "type": "transformation",
      "data": { ... }
    },
    {
      "type": "workflow",
      "data": { ... }
    }
  ],
  "readme": "Markdown text goes here"
}

Configuring Multiple Pre-Built Repositories

Itential Platform supports the configuration of multiple Prebuilt 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 Itential Platform environment.

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

Repository Configuration Properties

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

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

Sample Repository Configuration

Below is a sample configuration for repoConfigs.

{
    ...
    "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 Itential Platform such as the following:

Managing Pre-Built Repository Configurations

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

Figure 14: Admin Essentials Repositories

In the Browse menu, a user can select from a dropdown the repository configuration that will be used to fetch Pre-built Automations.

The sidebar has a Repositories section that allows a user to manage their repository configurations. A user has the ability to create, edit, or delete a configuration. In addition to these options, a user can also select to View All which will allow the user to view all of the repository configurations currently on the system.

Figure 15: Manage Repository Configurations

Editing a repo config can be done from the Repository Config details page.

Figure 16: Edit Repository Config

Adding a New Repository

A user can create a new repository configuration by going to the Repositories menu item of the Pre-built section of Admin Essentials and selecting the Create button in the upper left button bar. 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": {}
    }
}

Modifying a Repository Configuration

A user can edit an existing repository configuration by going to the Repositories menu item of the Pre-built section of Admin Essentials and selecting Edit repository details. A dialog will appear, prompting the user to modify each property that can be edited.

Connecting/Disconnecting a Repository Configuration

A user can connect or disconnect an existing repository configuration by going to the Repositories menu item of the Pre-built section of Admin Essentials and selecting the target configuration. A dialog will appear with all of the existing properties for the selected repository configuration. At the top of the dialog there is a toggle that can be switched on/off which represents the repository configuration being 'connected' or 'disconnected'.

Deleting a Repository Configuration

A user can delete an existing repository configuration by going to the Repositories menu item of the Pre-built section of Admin Essentials and selecting the target configuration. Then choose "Delete" in the more button at the upper right side. A dialog will appear, prompting the user to select a repository configuration to delete.

Viewinging 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.