Overview - Troubleshooting

In order to troubleshoot an adapter, it is valuable to understand some of the key components and concepts of Itential adapters. While there are a handful of adapters that do not follow this standard (database adapters and kafka), the vast majority of opensource adapters are built on the same foundation.

Key Components

Troubleshooting an adapter often involves making modifications to the adapter configuration or code. Listed below are important components of an adapter that may need to be changed in order to get the adapter working.

In this documentation, an overview of these key components is provided, but there are other adapter “How To” guides that cover each of these components in better detail.

• IAP Service Instance Configuration: Defines the properties used for your specific adapter instance within IAP. You can set the values for each of the properties in IAP Admin Essentials. There is a sampleProperties.json file in the /adapter-home-dir that contains sample values for each property.
• Endpoint Configuration - Defines the configuration for all calls the adapter can make to the other systems. Endpoints are located within each adapter entity in the entities directory in the adapter (e.g. /adapter-home-dir/entities/specific-entity). There are two "hidden" entities: the .generic entity is used for Generic Adapter Requests and the .system entity is used for token requests and defining the adapter healthcheck call.
  • action.json: Located within each adapter entity, defines the calls/actions that are available for that entity such as create, retrieve, update and delete.
  • schemas: Associated with each call/action. Defines the data sent to and received from the other system and how to translate the data between IAP and that system. There can be many schema files as each call made to a system can have a request schema and a response schema. These are defined in the action.json
• adapter.js: Integration point between the adapter and the rest of the Itential Automation Platform (IAP). Defines the data sent by IAP into the adapter, formats that data in the manner required by the adapter runtime libraries, and handles returning the expected result to IAP. You can modify the code in this component to get your customized adapter to work as desired.
• pronghorn.json: Second integration point between the adapter and the rest of the Itential Automation Platform (IAP). Defines the methods available to IAP and IAP Automation Studio. It also defines the data types for each input the method requires and the format of the output the adapter will return to IAP. This information should be tightly coupled with what is in the method signature in the adapter.js. There are unit test to verify that the information is in sync between the two files.

Key Concepts

Given that an adapter provides communication between the Itential Automation Platform (IAP) and another system, you should understand the following concepts. Several of these concepts also have their own “How To” guide that provides more detailed information.

• Authentication: Every adapter connects to another system in order to perform actions in that system. For this to happen, authenticating with that system is often a requirement. Adapters support different ways of authentication; however, you may need to determine the correct authentication method for the system you are integrating with and configure the adapter accordingly.
• Linting and Testing: Adapters should lint and test clean if they have been built by the Adapter Builder. Hence, anytime you build or customize an adapter, be sure the linting and testing for your adapter is clean as this is very important to the adapter’s successful performance.
• Connectivity: The server that IAP and the adapter is running on must be able to get to the server that the other system is running on. This may require firewall configurations to allow traffic through. It is important to check connectivity from the system where the adapter is (IAP Server) to the other system. If using a proxy, you should verify connectivity and configuration of the proxy and also make sure the proxy is configured properly in the IAP Service Instance Configuration for the adapter.