Login
Contents x
Base Properties
  • 09 Dec 2022
  • Dark
    Light
  • PDF
Contents

Base Properties

  • Updated on 09 Dec 2022
  • Dark
    Light
  • PDF
Article summary

Definition

Base properties for the adapter are contained within the top-level object within the IAP Service Instance Configuration for the adapter. In other words, they are not contained within other fields. Generally, these properties tell the adapter how to communicate with the external system.

Property Type Required Description
host string yes Hostname or IP address of the external system server. Without this information, the adapter will not be able to perform its essential function of communicating with the other system. The hostname does not include full url information - it is ONLY the hostname.

Example: In http://xyz.abc.com:8080/xyz/v1/abc the host name is xyz.abc.com.
port number yes Port on which to connect to the external system. Without this information, the adapter will not be able to perform its essential function of communicating with the other system. Even if you are using the default ports be sure to verify the port number in this property.

Example: In http://xyz.abc.com:8080/xyz/abc the port is 8080.

When a URL appears as http://xyz.abc.com/xyz/v1/abc, it is utilizing the default port. The HTTP default is 80 and the HTTPS default is 443.
choosepath string no -> "" Adapters have the ability to support different paths on calls based on the API verison of downstream system. This property allows users to control which path they want to utilize for the call. This is a new capability and the Endpoint Configuration for the adapter must have an array of entitypaths in order to use choosepath.

Note: If property is not set, choosepath will default to the first API version.
base_path string no -> "" A base path appears in most, if not all, of the API calls. You can override the base path on individual actions as needed in the Endpoint Configuration for the adapter. Using base path makes it easier to maintain the adapter whenever changes are made to the API paths.

Note: If it changes from/xyz to /api/rest, then you only need to change the property instead of having to change the entitypath on every action in the Endpoint Configuration for the adapter.

Example: http://xyz.abc.com:8080/api/rest/v1/abc the base path is /api/rest.
version string no -> "" Version is like base path in that it appears in most, if not all, of the API calls. You can override the version on individual actions as needed in the Endpoint Configuration for the adapter. Using version makes it easier to maintain the adapter whenever changes are made to the API paths.

Note: If it changes from v1 to v1.5, then you only need to change the property instead of having to change the entitypath on every action in the Endpoint Configuration for the adapter.

Example: In http://xyz.abc.com:8080/api/rest/v1.5/abc the version is v1.5.
cache_location enum no -> none Determines where the entity cache will be stored. Some brokers will check if an adapter can perform an action on an entity prior to requesting the action be done. In those scenarios, it is more efficient for the adapter to maintain entity lists in cache. If the adapter you are building has no need to cache basic entity lists, do not use caching as there is some overhead involved.

The following values are supported none – No caching; local – In memory (cache lost if adapter restarts).
encode_pathvars boolean no -> true This tells the adapter if the path variables should be URL encoded or not. The default behavior is to encode the path variables so that things like ? or slash are not signifying typical url behavior. This property can turn this behavior off.
encode_queryvars boolean no -> true This tells the adapter if the query variables should be URL encoded or not. The default behavior is to encode the query variables so that things like ? or slash are not signifying typical url behavior. This property can turn this behavior off.
save_metric boolean or string no -> false The adapter now collects metrics on each call. These metrics automatically provide information on the individual call. If save_metric is turned on, metrics will be maintained so that over time you will be able to see the success rates and average times for every action within the adapter.

Note: If save_metric is set to true, the metrics will be placedd into a storage directory inside the adapter.

If a string is provided, the adapter will assume this to be the path where you want the metrics stored and store them there.
stub boolean no -> false This flag determines whether the adapter should run standalone with mock data or integrated to the external system. When the adapter is deployed this should almost always be false. It can be set to true when running unit tests, performing integration tests with mock data, or when the adapter is running integrated with IAP to test capabilities like workflow, but not connected to the other system because that system may not be available in the development environment.
protocol enum no -> http The protocol the adapter should use to communicate to the other system. The adapter currently supports the following protocols: HTTP & HTTPS

Example Scenario Simple

  • In this example, the adapter wants to communicate with a system that is at mysystem.abc.com
  • It uses the HTTPS protocol on port 3443.
  • All requests to this system start with /api/rest.
  • The system is currently running v2.3 of its API, the complete endpoint should look like this: https://mysystem.abc.com:3443/api/rest/v2.3/specificpathforaction
  • There is no caching of entities.
  • Metrics will be saved for the request.
  • The adapter does not currently have multiple paths per call.
  • This example will run in production mode and communicate with the other system.

IAP Service Instance Configuration Properties for the Adapter

SAMPLE PROPERTIES 
"host": "mysystem.abc.com",
"port": 3443,
"choosepath": "",
"base_path": "/api/rest",
"version": "v2.3",
"cache_location": "none",
"encode_pathvars": true,
"encode_queryvars": true,
"save_metric": true,
"stub": false,
"protocol": "https"

Example Scenario Some Complexity

  • In this example, the adapter wants to communicate with a system that is at mysystem.abc.com
  • It uses the HTTPS protocol on the default port 443.
  • There is no generic start to any requests.
  • The system does not have version its API, the complete endpoint should look like this: https://mysystem.abc.com:443/getmy/specificpathforaction
  • There is no caching of entities.
  • Metrics will not be saved for the request.
  • There should be no url encoding of path variables but query variables should still be url encoded.
  • The adapter supports multiple paths per call. So, the entitypath in the action.json is an object with the following key value pairs:
    • "2020v": "{base_path}/{version}/getmy/pathforaction"
    • "2021v": "{base_path}/{version}/getmy/specificpathforaction"
  • This example will run in production mode and communicate with the other system.

IAP Service Instance Configuration Properties for the Adapter

SAMPLE PROPERTIES 
"host": "mysystem.abc.com",
"port": 443,
"choosepath": "2021v",
"base_path": "/",   (or empty "")
"version": "",
"cache_location": "none",
"encode_pathvars": false,
"encode_queryvars": true,
"save_metric": false,
"stub": false,
"protocol": "https"
Was this article helpful?
What's Next
Privacy Policy
Cookie Policy
Terms of Use
EULA
Copyright © 2022 Itential for Developers
Change password!
Changing your password will log you out immediately. Use the new password to log back in.
Change profile
Success!
First name must have atleast 2 characters. Numbers and special characters are not allowed.
Last name must have atleast 1 characters. Numbers and special characters are not allowed.
Enter a valid email
Enter a valid password
Your profile has been successfully updated.
Logout