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