Adapters & Custom Applications

This guide provides Itential users with instructions on how to install Adapters and Custom Applications on Itential Platform 6 when:

• Upgrading from a historical version of the Platform software, which requires you to migrate adapters or custom apps to the appropriate folder.

• Performing a fresh install of Platform 6, which requires you to be aware of the appropriate installation procedures for Adapters and Custom Applications in the new version of the Platform.

Before proceeding, here's a few noteworthy differences to be aware of:

• Alongside the change to RPM for deployment, Itential Platform 6 installs to a different location on-disk than the legacy Platform release versions (22.1/23.1/23.2).

• For the product to function, it's important to make note of the appropriate location for adapters and custom applications in Platform 6. The installation destination (folder) differs between Platform 6 and the Itential Platform releases (22.1/23.1/23.2).

Migration to Platform 6

To migrate, move and copy adapters from your current (legacy) Itential Platform version to the new Platform 6 release:

1. Locate adapters on your current Itential Platform system.

   /opt/itential/pronghorn/node_modules/@ itentialopensource
   

2. Go into an individual adapter.

   cd adapter-name
   

3. Remove the node_modules directory.

   rm -rf node_modules
   

4. Remove the package-lock.json.

   rm package-lock.json
   

5. Change directory out of the adapter.

   cd ..
   

6. Package and compress the adapter you are working on (zip, gzip, tar).

7. Move the compressed adapter to the new Platform 6 system.

8. Change adapter directory to the Platform 6 Services directory.

   /opt/itential/platform/services
   

9. Decompress the compressed file into the adapter directory. The services directory should contain the individual adapters and not a namespace.

10. Repeat steps 1-9 for all adapters on the current Itential Platform, including any custom adapters that are located in a custom namespace.

11. Follow steps 3 and 4 in the adapter installation section below for each adapter.

12. When you have migrated all of your adapters to Platform 6, follow steps 5-9 of the install below. This is so you will only need to restart the platform once after all adapters have been migrated.

Installation

To install an adapter:

1. Go to the Itential Platform Services directory: cd /opt/itential/platform/services

2. Clone, unzip, or tar the adapter into your Itential Platform environment. Use one of the methods below:

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

3. Install the adapter dependencies:

   1. cd adapter-name
   2. npm install

4. Lint and test the adapter:

   1. npm run lint:errors - There should be none.
   2. npm run test - All tests should pass.

5. Restart the Itential Platform.

6. Run the following to confirm restart: systemctl restart pronghorn

7. Create an adapter service instance in the Itential Platform Admin Essentials GUI.

8. Configure a service instance configuration for the adapter in the Itential Platform Admin Essentials GUI.

   1. Copy the properties from the sampleProperties.json in the adapter directory and place into the inner (second) properties in the Admin Essentials Service Instance Configuration for the adapter.
   2. Make all specific changes such as host, port, authentication method, credentials, etc.

9. Set the admin permission role to the adapter for anyone:

   1. Building workflows containing an adapter task.
   2. Using calls into the adapter for retrieving dynamic data in a JSON form, or within other custom applications.

Usage

Once the adapter has been installed, configured, and permissions set to the appropriate role, the adapter and its tasks should be available to users of the Itential Platform. Moreover, adapters are flexible with a high degree of customization for a variety of needs and use cases:

• You can add tasks to a workflow in Automation Studio and then run that workflow.
• You can add dynamic dropdowns that retrieve the list of data from an adapter.
• You can integrate the adapter with the Device Broker, which will add devices to Configuration Manager.
• You can access the adapter methods from your custom applications.
• You can access the adapter methods through Itential Platform API calls.

Limitations & Workarounds

A call must exist in the adapter in order to be available. As vendors update APIs, the calls may be missing from adapters. When this occurs, you can use the generic adapter tasks to prevent being blocked while a call is added.

Almost all open source adapters come with generic adapter calls that allow you to define endpoints and parameters. These calls can be used when a call is missing from an adapter, or when call parameters have changed. It further allows you to make progress on your use cases while the adapter is being updated to support the additions.

Further adapter documentation can be found in the Itential Opensoure library space: Adapters.

Logging

Adapter debug logs are essential to triage adapter issues. The debug logging that's been enabled includes: OPTIONS, REQUEST and CALL RETURN.

Testing

Once the adapter has been installed:

• Build and run a workflow with some simple calls.
• Create a JSON form and add a dynamic dropdown that utilizes an adapter call.

For device broker integration:

• Ensure the system has devices (e.g., Meraki) and there's access to the system.
• Go to the Admin Essentials GUI to verify broker integration for the adapter through the service instance configuration.
• Go to Configuration Manager to see if it was able to discover the devices in the down stream system. If not, you may need to confirm the device broker mappings in the adapter.

Troubleshooting & Support

Typical adapter issues center around configuration and authentication. The adapter sampleProperties should have authentication techniques that were previously used or were documented to work with the adapter. In addition, every open source adapter should have an AUTH.md file that describes the login process and criteria.

When using SSL/TLS, you will need to enable SSL in the adapter service instance configuration. This also requires you to provide a ca file or to turn on accept invalid certs. The latter is not recommended for production, but is generally acceptable for development and testing.

If you experience any problems or can’t figure out how to make a change, please contact the Itential Adapters Team using this link: Here to Help

Technical Resources

• Adapter Configurations and Customizations
• Generic Adapter Methods
• Using Adapter API in JSON Form Dropdowns

Related Reading

Platform 6

• Configuration Enhancements
• Installation
• Upgrade