Troubleshoot

Troubleshoot adapters overview

The vast majority of open-source Itential adapters are built on a shared foundation. Understanding that foundation is the starting point for effective troubleshooting. A small number of adapters — such as database and Kafka adapters — do not follow this standard and may require different approaches.

Key components

Troubleshooting an adapter typically involves modifying its configuration or code. The components most commonly involved are:

IAP service instance configuration defines the properties for your specific adapter instance withinItential Platform. Values are set inItential Platform Admin Essentials. A sampleProperties.json file in /adapter-home-dir provides sample values for each property.

Endpoint configuration defines all calls the adapter can make to the external system. Endpoints are located within each adapter entity at /adapter-home-dir/entities/<entity-name>. Two hidden entities serve special purposes: .generic handles generic adapter requests, and .system handles token requests and the adapter health check call.

Within the endpoint configuration, two files matter most:

  • action.json — defines the calls available for a given entity, such as create, retrieve, update, and delete.
  • Schemas — define the data sent to and received from the external system, and how to translate it betweenItential Platform and that system. Each call can have a request schema and a response schema; both are referenced in action.json.

adapter.js is the integration point between the adapter andItential Platform. It defines the dataItential Platform passes into the adapter, formats it for the adapter runtime libraries, and returns results toItential Platform. You can modify this file to customize adapter behavior.

pronghorn.json is the second integration point withItential Platform. It defines the methods available toItential Platform andItential Platform Automation Studio, the data types for each method’s inputs, and the format of the output the adapter returns. The method signatures here must stay in sync with adapter.js — unit tests verify this.

Key concepts

Authentication — most external systems require authentication. Adapters support multiple authentication methods. You may need to determine the correct method for the system you are integrating with and configure the adapter accordingly. See the Authentication overview for details.

Linting and testing — adapters built by the Adapter Builder should lint and test clean. After any code or configuration change, always verify that linting and tests still pass. Issues here often surface runtime problems. See Linting and Testing for details.

Connectivity — theItential Platform server must be able to reach the external system over the network. Firewall rules, proxy configuration, and SSL/TLS settings all affect connectivity. Check connectivity from theItential Platform server itself, not from your local machine. See Connectivity for details.