Adapter Properties

General Configuration

Definition

• host (string): Hostname or IP address of the external system server. This property is required. Without it, the adapter will not be able to perform its essential function of communicating with another system.
  • http://xyz.abc.com:8080/xyz/abc
• port (number): Port on which to connect to the external system. This property is required. Without it, the adapter will not be able to perform its essential function of communicating with another system. Even if you are using the default ports be sure to verify the port number in this property.
  • When a URL appears as http://xyz.abc.com/xyz/abc,
    it is utilizing the default port.
  • HTTP default is 80.
  • HTTPS default is 443.
• base_path (string): A base path appears in most, if not all, of the API calls. You can override the base path on individual actions as needed. Using base path makes it easier to maintain the adapter whenever changes are made to the system path. If it changes to /api/rest, then you only need to change the property instead of having to change the entitypath on every action in the adapter.
  •  http://xyz.abc.com:8080/api/rest/v1/abc
• version (string): 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. Using version makes it easier to maintain the adapter whenever changes are made to the API version. If it changes to v1.5, then you only need to change the property instead of having to change the entitypath on every action in the adapter.
  • http://xyz.abc.com:8080/api/rest/v1.5/abc.
• cache_location (enum): 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).
  • redis – In Redis (preserved across adapter restart – slightly less performant).
• save_metric (boolean or string): The adapter now collects metrics on each call. These metrics automatically provide information on the individual call. If save_metric is turned on, additional 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. If a string is provided, the adapter will create a storage directory within the adapter and assume that is the path to where the metrics are to be stored.
• stub (boolean): 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.
• protocol (enum): The protocol the adapter should use to communicate to the other system. The adapter currently supports the following protocols:
  • HTTP
  • HTTPS

Definition

All authentication properties are within the authentication object within the properties. If using request_token, there is also an action (getToken) defined in the .system entity that is used to define the token request.

• auth_method (enum): Required field. The authentication method used for the external system. The following methods are supported:
  • basic user_password: Authentication will always require a username and password.
  • static_token: Authentication is always done with a static token provided in the token property.
  • request_token: Authentication is initially done with a username and password which will return a token that can be used in subsequent requests.
  • no_authentication: No authentication is required to talk to the system or authentication will be done outside of the adapter run time libraries.
• username (string): Required for basic user_password and request_token. The username for authenticating with the other system
• password (string): Required for basic user_password and request_token. The password for authenticating with the other system. It can be encrypted through the adapter encryptProperty method or through IAP. Note: You must use encyptProperty of the adapter that will be specified using the property.
• token (string): Required for static_token only. The token to use when authenticating with the external system. This is only used when the authentication is static token and thus the token is known.
• token_timeout (integer): How long a token is valid before it will timeout when using dynamic tokens. The system will request a new token prior to the defined timeout. Special values include:
  • -1 – Always get a new token.
  • 0 – Use the expiration time returned with the token. Must be defined in the token schema response and have an acceptable format.
• token_cache (enum): When using dynamic token, this tells the adapter where to store the token until it expires.
  • Local – In memory. Lost if adapter restarts.
  • Redis – Preserved across adapter restart. Slightly less performant.
• invalid_token_error (integer): Error returned when a request is rejected with invalid token. Adapter will request new token.
• auth_field (string): Required. The field in the request to the external system where the authentication information is placed. For example, if the system expects it in header, then headers and then Authorization, this field should be set to header.headers.Authorization.
• auth_field_format (string): Required. The format of the field in the request that contains the authentication information. You can specify a combination of text and dynamic information.
  • For example, if you have b64 encoding for Basic Auth, this property may look like: {b64}Basic {username}:{password}{/b64}.
  • This tells the adapter to b64 encode a string that will look like “Basic myuser:mypasswd”.
  • You can also combine text with tokens by setting this property to Token {token} or Bearer {token}.

Authentication Call

• The call to get the token is: https://mysystem.abc.com:3443/api/rest/v2.3/login. The host, port, base_path, and version are defined in base properties. So the path defined here is just /login.
• It is a POST call as it has a body. The body sent to the other system contains two fields, user and passwd. The fields username and password are the IAP names for those fields.
• The response from the other system contains the field for access_token. This is what IAP calls the token and will use it in subsequent requests.
• For more authentication examples see the presentation on Adapter Authentication.

Definition

All healthcheck properties are within the healthcheck object within the properties. There is a “healthcheck” action defined in the .system entity that is used to define the healthcheck request.

• type (enum): Required field. The type of healthcheck to use.
  • none – Do not run any healthchecks.
  • startup – Run a healthcheck at start up only
  • intermittent – Run healthchecks at a defined interval.
• frequency (integer): Required if intermittent. The frequency in which to run intermittent healthchecks.

Example

• In this example, a healthcheck is set to run every 5 minutes (300s – 300000ms).
• The call for the healthcheck is a GET method: https://mysystem.abc.com:3443/api/rest/v2.3/getSystemStatus The host, port, base_path, and version are defined in base properties. So the path defined here is just /getSystemStatus.
• The data in the response is not the primary focus here, just that we got a response. For this example, we can use the default schema with no translation.

Definition

All request properties are within the request object within the properties. These tell the adapter libraries how to handle details that come up on a request.

• number_redirects (integer): If the adapter should allow redirects, this property tells the adapter how many redirects to allow before returning an error.
• number_retries (integer): Required if the request object. The number of times to retry a request that was either aborted or failed with a retry error before returning an error.

• limit_retry_error (integer or array): Required if the request object. An error that has been defined as one the adapter should re-attempt. Supports an array of integers or an array containing ranges (e.g., [401,“500-599”]).
• failover_codes (array of integers): List of error codes used by the adapter to send an error response that notifies the platform to attempt the request through another adapter, if available.
• attempt_timeout (integer): Required if the request object. Defines the time in milliseconds (ms) after which the adapter should abort a request and retry after the external system is available.

• global_request (object): Provides a way to have global data used in all requests the adapter makes. It is key that all values are static. Dynamic values are handled through adapter.js.
  • payload (object): If every payload sent to the other system is supposed to contain specific fields with static values, that part of the payload can be set here.
  • uriOptions (object): If every request sent to the other system is supposed to contain query fields with static values, those options can be defined here.
  • addlHeaders (object): If every request sent to the other system is supposed to contain specific headers with static values, those headers can be defined here.
  • authData (object): If every request sent to the other system is supposed to contain authentication data with static values, that data can be defined here.

• healthcheck_on_timeout (boolean): Required if the request object. Defines whether a healthcheck should be performed when a request has timed out to make sure the other system is still available.
• return_raw (boolean): Tells the adapter runtime libraries to return the raw response along with the results being returned. This is helpful to collect mock data but may also be required on some calls.
• archiving (boolean): Deprecated. Do not use except in a lab environment for testing the adapter.

Priority Queues

• The 1st priority is for blocking issues and these items need to be at the front of the queue.
  • When there is a priority 1 request, it will be matched to the first rule and put at the front of the throttle queue.
• The 2nd priority is for requests which are still critical but not critical enough to jump to the front of the line; they are put in the queue at 10% – in front of 90% of the current requests.
  • When there is a priority 2 request, it will be matched to the second rule and be put in the throttle queue after the first 10% of the requests.
• The 3rd priority is for request that are not critical to current business but should be prioritized above the normal usage; these are set at 50%.
  • When there is a priority 3 request, it will be matched to the third rule and put in the throttle queue after the first 50% of the requests.
• If there is no priority with the request it will be at the end of the throttle queue (100%).