AppsAdmin EssentialsPre-builts

Build automation repositories

The Itential Open Source Pre-Builts repository is no longer actively maintained. Those pre-builts have been certified up to Platform 2023.2, but can still be imported to Platform 6. We recommend transitioning to Projects for the best experience.

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 your custom pre-built automations.

Itential Platform supports the configuration of custom and multiple pre-built automation repositories. This means you can provide a configuration to fetch pre-built automations from your own custom repository, as opposed to previous releases where it was only possible to pull from Itential’s official open-source library.

The following conventions must be followed 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 branching strategy within each GitLab repository can be customized for development purposes; however, for a pre-built automation to properly appear in Admin Essentials, each must follow a specific branch naming convention considered as the release branches.

Pre-built automation 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.

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. The version uses the traditional major.minor.patch Semantic Versioning, followed by a dash (”-”) and the corresponding major release of Itential Platform (YYYY.Z), then each change to the prebuilt increments the maintenance number.

One branch can only support one version of Itential Platform. 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 must also be tied to a specific release by creating a branch named with release/YYYY.Z. This versioning scheme is accomplished by having different Git branches to reflect different release versions.

For example, if you have a custom pre-built automation, the repository branches would be:

$* master
$* release/2021.1 -> consumable byItential Platform release/2021.1
$* release/2020.2 -> consumable byItential Platform release/2020.2
$* release/2020.1 -> consumable byItential Platform release/2020.1

Structure of a pre-built automation

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 Itential Platform component files contained within the pre-built automation. An example directory structure for a pre-built automation that contains one of each supported component type (two transformations) would be:

$/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 file describes the contents and use-cases of the pre-built automation and is 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. It informs Itential Platform of the content along with the name, type, and location of each component in the bundle.

1{
2  "bundleName": "Custom Pre-built Automation",
3  "artifacts": [
4    {
5      "id": "Automation Catalog Name 1",
6      "name": "Automation Catalog Name 1",
7      "type": "ac-agenda-job",
8      "location": "/bundles/ac_agenda_jobs/automation-catalog-1.json"
9    },
10    {
11      "id": "Form Name 1",
12      "name": "Form Name 1",
13      "type": "forms",
14      "location": "/bundles/forms/form-1.json"
15    },
16    {
17      "id": "Golden Config Name 1",
18      "name": "Golden Config Name 1",
19      "type": "golden-config",
20      "location": "/bundles/golden-config/golden-config-1.json"
21    },
22    {
23      "id": "Json Form Name 1",
24      "name": "Json Form Name 1",
25      "type": "json-forms",
26      "location": "/bundles/json_forms/json-forms.json"
27    },
28    {
29      "id": "MOP Template 1",
30      "name": "MOP Template 1",
31      "type": "mop-template",
32      "location": "/bundles/mop_template/mop-template-1.json"
33    },
34    {
35      "id": "MOP Analytic Template 1",
36      "name": "MOP Analytic Template 1",
37      "type": "mop-analytic-template",
38      "location": "/bundles/mop_analytic_template/mop-analytic-template-1.json"
39    },
40    {
41      "id": "Service Catalog 1",
42      "name": "Service Catalog 1",
43      "type": "service-catalog",
44      "location": "/bundles/service_catalog/service_catalog-1.json"
45    },
46    {
47      "id": "Template 1",
48      "name": "Template 1",
49      "type": "template",
50      "location": "/bundles/template/template-1.json"
51    },
52    {
53      "id": "Transformation 1",
54      "name": "Transformation 1",
55      "type": "transformation",
56      "location": "/bundles/transformation/transformation-1.json"
57    },
58    {
59      "id": "Workflow Name",
60      "name": "Workflow Name",
61      "type": "workflow",
62      "location": "/bundles/workflow/workflow.json"
63    }
64  ]
65}

package.json

The package.json file follows conventions set by npm.

1{
2  "name": "Custom Pre-built Automation",
3  "version": "1.0.0-2021.1.1",
4  "description": "A description of the Pre-built Automation",
5  "author": "John Doe",
6  "license": "Apache-2.0",
7  "repository": {
8    "type": "gitlab",
9    "hostname": "gitlab.com",
10    "path": "/path/to/my/prebuilts-repo"
11  },
12  "IAPDependencies": {
13    "@itential/app-automation_catalog": "2.5.4",
14    "@itential/app-json_forms": "1.13.5",
15    "@itential/app-workflow_engine": "6.7.10"
16  }
17}

artifact.json

The artifact.json file is the most important aspect of the pre-built automation. It 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.

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.

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

1{
2  "metadata": {
3    "name": "Custom Pre-built Automation",
4    "version": "1.0.0-2021.1.1",
5    "description": "A description of the Pre-built Automation",
6    "author": "John Doe",
7    "license": "Apache-2.0",
8    "repository": {
9      "type": "gitlab",
10      "hostname": "gitlab.com",
11      "path": "/path/to/my/prebuilts-repo"
12    },
13    "IAPDependencies": {
14      "@itential/app-automation_catalog": "2.5.4",
15      "@itential/app-json_forms": "1.13.5",
16      "@itential/app-workflow_engine": "6.7.10"
17    }
18  },
19  "manifest": {
20    "bundleName": "Custom Pre-built Automation",
21    "artifacts": [
22      {
23        "id": "Automation Catalog Name 1",
24        "name": "Automation Catalog Name 1",
25        "type": "ac-agenda-job",
26        "location": "/bundles/ac_agenda_jobs/automation-catalog-1.json"
27      },
28      {
29        "id": "Workflow Name",
30        "name": "Workflow Name",
31        "type": "workflow",
32        "location": "/bundles/workflow/workflow.json"
33      }
34    ]
35  },
36  "bundles": [
37    { "type": "ac-agenda-job", "data": { ... } },
38    { "type": "forms", "data": { ... } },
39    { "type": "golden-config", "data": { ... } },
40    { "type": "json-form", "data": { ... } },
41    { "type": "mop-template", "data": { ... } },
42    { "type": "mop-analytic-template", "data": { ... } },
43    { "type": "service-catalog", "data": { ... } },
44    { "type": "template", "data": { ... } },
45    { "type": "transformation", "data": { ... } },
46    { "type": "workflow", "data": { ... } }
47  ],
48  "readme": "Markdown text goes here"
49}