Troubleshooting

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 specifically cover each of these components in better detail.

• Properties:  Defines the properties for your specific adapter.
• 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.
• 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.

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.

Install Locations

• Adapters are defined in a namespace. This is important to understand as the adapter should be in that namespace within the IAP node_modules.
• Most Itential adapters exist in the @itentialopensource name space. This means they should be installed in the <IAP Home>/node_modules/@itentialopensource directory. For example:
  • /opt/pronghorn/current/node_modules/@itentialopensource/adapter-aws_ec2
• There are Itential adapters that come with IAP by default which are in the @itential namespace. These adapters include several IAP authentication adapters (e.g., adapter-ldap) as well as some of the more specialized orchestration adapters (e.g., adapter-nso).
• There are also custom adapters that Itential Delivery or our customers build that may have their own namespace (e.g., @mycompany). These adapters would be installed in their own namespace directory. For example:
  • /opt/pronghorn/current/node_modules/@mycompany/adapter-mycustomadapter

Note: If the adapter is not installed in the proper directory, the adapter will fail to load when IAP is restarted.

Dependencies

• It is important to remember that adapters have dependencies.
  • Most of the adapter code exists in its runtime libraries. This helps to provide new capabilities and allow those capabilities to be available to all adapters.
  • These dependencies should be installed within the node_modules directory of the adapter.
• Do not install dependencies within the IAP node_modules directory.
  • To install the adapter dependencies, run npm install within the adapter directory.

Connectivity

Adapters need to connect with the system they are trying to communicate with.

• We often assume the connectivity is there when it may not be.
• Here are a few ways to check connectivity:
  • Use ping from the IAP server to make sure you can see the other server.
  • Use telnet from the IAP server to the server and port of the other system.
  • If connectivity appears to be blocked, run traceroute (or an equivalent command) to determine where the connectivity is blocked. This will help provide the appropriate team with the information they need to open access.
  • Run a curl command from the IAP server to the other system.
  • Note: If the adapter is not configured with the correct connectivity information, the adapter will load but the healthcheck (if configured to run) will fail when IAP or the adapter is restarted. Also, all other adapter calls will fail to execute successfully (often resulting in a 400 or 404 error).
• Connectivity also requires you to configure these adapter properties:
  • host
  • port
  • protocol
  • ssl sub-properties
• For development/lab, set accept_invalid_cert = true.
• For production, use ca_file.

Path

Adapters need to send the request to the correct path for the other system to receive and handle the request properly.

• For example, if the path is /api/rest/v3/device and we are sending /api/v2/device, the call will result in an error or not be handled properly.

Having the correct path for installation requires configuring adapter properties like these:

• base_path
• version

To verify you have the correct path:

• Make sure base_path is correct. Using base path is helpful to minimize the impact of any changes but the wrong base path will result in all calls failing.
• Make sure base_path is only the common part of the path for all calls.
• Base_path should not include connectivity information like protocol, host or port

Authentication

Adapters often need to authenticate the system they are trying to communicate with. Authentication includes:

• Configuring properties within the authentication sub-section such as:
• auth_method
• credentials (username, password, token)
• auth_field
• auth_field_format

If authenticating with a dynamic token, configure the .system entity:

• getToken action – Defines the call to use to get the token
• Schema files used by getToken – Defines how the data will be sent on the token request as well as defining where the adapter can find the token in the response.

Linting

The adapter should include lint rules and test scripts.

• Lint the adapter when you first install it to make sure it lints clean.
• While linting errors are not always related to run time issues, fixing linting issues can often help you prevent run time issues from occurring.

As a best practice always make sure the adapter lints clean after making any code or configuration changes.

Note: If the adapter does not lint properly, the adapter may fail to load when IAP is restarted. Lint issues can also cause runtime issues with calls to the other system.

Testing

The adapter should include lint rules and test scripts.

• Lint the adapter when you first install it to make sure it lints clean.
• While linting errors are not always related to run time issues, fixing linting issues can often help you prevent run time issues from occurring.
• As a best practice always make sure the adapter lints clean after making any code or configuration changes.

Note: If the adapter does not test properly, the adapter can have runtime issues with 1 or more calls to the other system.

Troubleshooting Scenarios

Adapter is not in IAP

• I installed my adapter and restarted the Itential Automation Platform (IAP), but the adapter is not listed.
  • Recheck some of the basic common areas:
    • Make sure the adapter is installed in the correct namespace.
    • Make sure the adapter dependencies were installed in the adapter directory
    • Make sure the adapter lintsclean. Some lint errors (e.g. syntax errors) can cause failures when IAP attempts to load the adapter.
  • Check the IAP logs. There will most likely be an error log on why IAP was unable to start the adapter.
    • If you are unable to determine the issue by looking at the log, create a ticket with the log information and the Itential Adapters Team will be happy to assist.
  • In newer versions of IAP, there are requirements for the pronghorn.jsonfile. These requirements may cause issues with the adapter loading and can result in log errors.
    • Note: If an adapter was built prior to November 2019 and has not been migrated to a newer version, this can also lead to failure when IAP attempts to load the adapter.

Adapter status is red

• My adapter shows up in IAP but one of the status indicators is red.
  • If the first status is red, the adapter did not come up and you should follow the process in the previous slide.
  • If the second status is red, the adapter is up but health check has failed.
  • Recheck some of the basic common areas:
    • Make sure the adapter has connectivity.
    • Make sure the adapter has the proper path.
    • Make sure the adapter is configured for the correct authentication.
  • Put the adapter into debug level logging. This is critical to determine what the adapter is doing and be able to compare it to what it is supposed to do. See section on debug logging.
    • It might be easier to run integration testing from the adapter with debug logs turned on to test the healthcheck. You need to set up the integration test and log level first and then you will be able to see what happens on your screen.
  • Run the command used for healthcheck in Postman or Curl to provide a comparison on what works.
  • You may need to make changes to the healthcheck configuration, namely:
    • Changes to properties.
    • Changes to the healthcheck action defined in the .system entity. The healthcheck action is used to define the call that will check if the other system is available.

Adapter is up, but no calls work

• Everything looks good but none of the adapter calls seem to work.
  • In some cases healthcheckhas been set to “none” by default. If that is the case, enable healthcheck and then make sure the healthcheck call works. If not, please review the previous slide.
  • If the healthcheck call is working, then connectivity and authentication should not be the issue.
  • Recheck the base_pathand version
    • It is possible the healthcheck has a different path set up than the rest of the calls, or local changes were made to get it working. It may be necessary to make changes so that all calls are set up similarly.
  • Put the adapter into debug level logging. This is critical to determine what the adapter is doing and be able to compare it to what it is supposed to do. See section on debug logging.
    • It might be easier to run integration testing from the adapter with debug logs turned on to test the healthcheck. You need to set up the integration test and log level first and then you will be able to see what happens on your screen.
  • Run one of the commands in Postman or Curl to provide a comparison on what works.
  • You may need to make configuration changes to the properties and action.json for the entities.
    • Properties: If you change adapter properties make sure you do not break getToken or healthcheck.
    • Action.json: Defines the calls available for a specific entity. The action.jsonincludes things like path, method, data types, schemas, etc.

Adapter has one or more calls failing

• The adapter is generally working but there is at least one (1) call that is failing.
  • Check the unit test. This should tell you if there is an issue in the configuration for that action/call.
  • Put the adapter into debug level logging. This is critical to determine what the adapter is doing and be able to compare it to what it is supposed to do. See section on debug logging.
    • It might be easier to run integration testing from the adapter with debug logs turned on to test the healthcheck. You need to set up the integration test and log level first and then you will be able to see what happens on your screen.
  • Run the command in Postman or Curl to get a comparison on what works.
  • Focus on the OPTIONS and REQUEST logs to verify the information the other system expects is being sent in the proper format. If the format of the request is not what the other system expects, you may have to change the requestDatatypeor the requestSchema.
  • You may need to make configuration changes to the action.json and schema for the entities.
    • Action.json: Defines the calls available for the specific entity. The action.jsonincludes things like path, method, data types, schemas, etc.
    • Schema: Defines the data that will be sent to the other system.

Adapter not sending the proper request

• The call to the other system does not include the proper request data or the data is not formatted properly.
  • Check the requestDatatype and make sure it is set to the type of data the other system is expecting. The runtime libraries will attempt to do different things based on the datatype. If the datatype is not correct, the adapter may not format the request data properly.
  • Check the requestSchema and make sure it is handling the data as expected. The schema defines how to translate data so maybe the data is being put somewhere the other system does not expect or maybe it is being dropped from the request. Schema also handles things like encoding and encrypting individual data fields.
• You may need to make configuration changes to the action.json and schema for the entities.
  • Action.json: Defines the calls available for the specific entity. The action.json includes things like path, method, data types, schemas, etc.
  • Schema: Defines the data that will be sent to the other system.

Adapter not receiving correct response

• The call to the other system is returning but I am not getting the data that I expected, or the adapter is having issues with the response.
  • Check the responseDatatype and make sure it is set to the type of response data you are expecting. The runtime libraries will attempt to do different things based on the datatype. If the datatype is not correct, the adapter may not format the response data properly.
  • Check the responseSchema and make sure it is handling the data as expected. The schema defines how to translate data so maybe the data is being put somewhere you do not expect or maybe it is being dropped from the response. Schema also handles things like decoding, decrypting and parsing individual data fields.
• You may need to make configuration changes to the action.json and schema for the entities.
  • Action.json: Defines the calls available for the specific entity. The action.json includes things like path, method, data types, schemas, etc.
  • Schema: Defines the data that will be sent to the other system.

Adapter tasks are not in workflow

• My adapter is loaded into IAP, but the adapter tasks do not appear in the workflow.
  • Make sure the adapter is truly up in IAP. If not, you will need to get the adapter up. Consult the earlier section (“My adapter is not in IAP”) for more information.
  • Make sure the adapter methods are in the pronghorn.json file and the task flag is set to true.
  • Make sure the adapter configuration in IAP is set correctly. Pay attention to the adapter type and make sure it is referencing the correct adapter. The type should match the export in the pronghorn.json file which should also match the module.exportsline in adapter.js.
  • Check the IAP logs. There will most likely be an error log on why it was unable to load the workflows.
• If you are unable to determine the issue by looking at the log, create a ticket with the log information and the Itential Adapters team will be happy to assist.