Platform On-PremInstall

Install and migrate adapters and custom applications

This guide covers installing adapters and custom applications on Platform 6, including how to migrate them from a previous Platform version.

Before you proceed, note the following differences in Platform 6:

  • Platform 6 installs to a different on-disk location than earlier Platform releases (2022.1, 2023.1, 2023.2).
  • Adapters and custom applications must be placed in the correct services directory for the product to function.
Platform versionServices directory
2022.1 / 2023.1 / 2023.2/opt/itential/pronghorn/node_modules/@itentialopensource
Platform 6/opt/itential/platform/services

Migration to Platform 6

Use this procedure to migrate adapters from a legacy Platform installation to Platform 6.

1

Locate existing adapters

On your current Platform system, find the adapters directory:

/opt/itential/pronghorn/node_modules/@itentialopensource
2

Remove generated files from each adapter

For each adapter you intend to migrate:

$cd adapter-name
$rm -rf node_modules
$rm package-lock.json
$cd ..
3

Package and transfer each adapter

Compress each adapter using zip, gzip, or tar, then transfer the compressed file to the Platform 6 system.

4

Place adapters in the Platform 6 services directory

On the Platform 6 system, decompress each adapter into:

/opt/itential/platform/services

The services directory should contain individual adapter directories directly — not a namespace directory wrapping them.

5

Install dependencies for each adapter

$cd /opt/itential/platform/services/adapter-name
$npm install
6

Run lint and tests

$npm run lint:errors   # Should produce no errors
$npm run test          # All tests should pass
7

Restart the Platform

After all adapters have been migrated, restart once:

$systemctl restart itential-platform
8

Configure service instances

For each adapter, complete the configuration steps in the Install an adapter section below.

Repeat this procedure for all adapters on the legacy system, including custom adapters in non-standard namespaces.

Install an adapter

2

Add the adapter

Use one of the following methods:

$git clone git@gitlab.com:@itentialopensource/adapters/adapter-name
$unzip adapter-name.zip
$tar -xvf adapter-name.tar
3

Install adapter dependencies

$cd adapter-name
$npm install
4

Run lint and tests

$npm run lint:errors   # Should produce no errors
$npm run test          # All tests should pass
5

Restart the Platform

$systemctl restart itential-platform
6

Create a service instance

In the Admin Essentials GUI, create a new service instance for the adapter.

7

Configure the service instance

In the Admin Essentials GUI, open the service instance configuration for the adapter.

Copy the properties from sampleProperties.json in the adapter directory and paste them into the inner (second) properties object in the service instance configuration. Update host, port, authentication method, credentials, and any other environment-specific values.

8

Set permissions

Grant the admin role to the adapter for any user who will:

  • Build workflows that include an adapter task
  • Use adapter calls to retrieve dynamic data in a JSON form or custom application

Adapter high availability setup

In a high availability (HA) cluster, you must install the adapter source code on every node before creating the adapter instance. This ensures the adapter can run on any node in the cluster.

1

Install adapter source code on all nodes

On every node in the cluster, follow the Install an adapter steps above.

2

Restart the Platform on all nodes

$systemctl restart itential-platform
3

Create an adapter instance

From any node, open Admin Essentials and create a new adapter instance. See Adapters for instructions.

4

Configure the adapter

In the Configuration tab, edit the service config to match your environment, then click Save. Saving automatically restarts the adapter on that node.

5

Restart Platform on all remaining nodes

The auto-restart in the previous step only affects the node where you saved the config. On each remaining node, restart Itential Platform so that it loads the new adapter instance from the shared database:

$systemctl restart itential-platform

The adapter instance is now running on all nodes in the cluster.

Adapter logging

Adapter debug logging captures three event types:

Log eventDescription
OPTIONSConfiguration and metadata for the call made to the downstream system
REQUESTPayload sent to the downstream system
CALL RETURNRaw response received from the downstream system

Troubleshooting

Most adapter issues relate to configuration and authentication. Check the adapter’s sampleProperties.json for documented authentication approaches, and the AUTH.md file for a description of the login process and requirements.

When using SSL/TLS, enable SSL in the service instance configuration and provide a CA file. Accepting invalid certificates is not recommended for production environments.

For missing or outdated API calls, use the adapter’s generic methods to continue work while a formal update is added. Generic adapter calls let you define custom endpoints and parameters directly.

For additional support, contact the Itential Adapters Team: Here to Help.