Pre-Built Automation Repository (Custom Set Up)

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

Itential Automation Platform (IAP) 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. For more on Pre-built Automation repository configuration, please refer to the Pre-builts section of the Admin Essentials User Guide.

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

Structure of a Pre-built Automation Repository

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.

Pre-built Automation Versioning Requirements

Every IAP release has a version which follows the convention below:

x.y.z-2021.1.m

The "2021.1" equates to the major release of IAP and the "m" is the maintenance release.

In order for a Pre-built Automation to be consumed by an IAP 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 IAP (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).

Important Note: One branch can only support one version of IAP. For the version checking features to function properly, these rules must be followed on creation of the Pre-built Automation.

Branch Naming Requirement for Pre-built Automations

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 IAP:

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

bundles

The bundles directory consists of a directory map of all the IAP 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 IAP environment (see the Automation Studio guide to find the "export" capability for the majority of the components and the Configuration Manager and Service Catalog guide for the others) and will be used to import the component into the new IAP environment during import/install of a Pre-built Automation.

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

NOTE: For ease of reading, the actual content for the bundles directory is represented by ellipses.

{
  "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"
}