Automation Gateway Adapter
The Automation Gateway adapter is used to integrate IAG with Itential Platform through the IAG API. Use the information in this guide to set property values and other parameters for adapter-automation_gateway
. These properties tell the adapter how to communicate with the system.
Adapter Properties
Configure these properties to establish connectivity and define adapter behavior.
Property | Type | Description |
---|---|---|
host |
String | Required. The hostname of the Automation Gateway adapter. |
port |
Number | Required. The port on which to connect to the adapter. Default port: 443 . |
choosepath |
String | This property allows users to control which path to utilize for an API call. The Endpoint Configuration for the adapter must have an array of entitypaths in order to use choosepath . For the gateway adapter, the choosepath property can be empty (left blank) or set to v0 to work in default mode. To honor the base_path configuration listed below, the value of choosepath must be set to v1 . |
base_path |
string | A base path appears in most, if not all, API calls. Users 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 path. If the path changes from /xyz to /api/rest , users only need to change the property instead of having to change the entitypath on every action in the Endpoint Configuration for the adapter.Example: For http://xyz.abc.com:8080/api/rest/v1/abc the base path is /api/rest . |
version |
String | Required. Used to set the current API version the adapter integrates with. Default: v2.0 . |
authentication |
Object | Required. Defines the properties used for authentication. |
stub |
Boolean | Defines whether the stub should run instead of making calls to Automation Gateway. Useful during basic testing. Default is false (i.e., connects to Automation Gateway). |
protocol |
String | Notifies the adapter whether to use HTTP or HTTPS. Default is http . |
healthcheck |
Object | Required. Defines the types of health check settings currently supported. |
throttle |
Object | Defines the properties used to throttle requests to Automation Gateway. |
request |
Object | Defines the properties used to handle requests and responses. |
proxy |
Object | Defines the properties used to handle requests and responses. |
ssl |
Object | Required. Defines the properties to utilize SSL authentication with Automation Gateway. |
strip_escapes |
Boolean | Strips out additional backslashes from all API calls. The default setting is off, false . To enable, change to true . The default setting is recommended unless an issue arises where extra escape characters (i.e., backslashes) are added to API calls that should be removed. |
Authentication
Configure authentication methods for secure communication with Automation Gateway.
Property | Type | Description |
---|---|---|
auth_method |
String | Defines the authentication method used in requests. Valid authentication methods include request_token (default), static_token , and no_authentication . |
username |
String | The username to authenticate with Automation Gateway on every request or when pulling a token that will be used in subsequent requests. |
password |
String | The password to authenticate with Automation Gateway on every request or when pulling a token that will be used in subsequent requests. If retrieved through an encrypt password call, use the exact return including the {code} . |
token |
String | Defines a static token that can be used on all requests. |
token_user_field |
String | The field in the token request where the username credential should be provided. |
token_password_field |
String | The field in the token request where the password credential should be provided. |
token_result_field |
String | Defines the field in the token response where the actual token will be. |
token_URI_path |
String | The API path used to retrieve a token. |
token_timeout |
Number | Defines how long a token is valid. Measured in milliseconds. Once a dynamic token is no longer valid, Itential Platform has to pull a new token. Default is -1 (minus one), which means Itential Platform pulls a token on every request. Maximum value is 3600000 . |
invalid_token_error |
Number | Defines the HTTP error that is received when a token is invalid. Notifies the adapter to pull a new token and retry the request. Default: 401 . |
auth_field |
String | Defines the header field in which to place the token. |
auth_field_format |
String | Defines the format used to pass the authentication variables. |
Healthcheck
Use healthchecks to monitor your adapter's connectivity to the Automation Gateway and ensure reliable communication.
Choose from these healthcheck types:
- Startup (Recommended) - The adapter checks for connectivity during startup and performs no additional checks afterward. This option provides simplicity and prevents unnecessary errors that can occur when a health check fails but the Automation Gateway becomes available before the next scheduled check.
- Intermittent - The adapter checks connectivity to the Automation Gateway at the frequency defined by the
frequency
property. - None (Not recommended) - The Itential Platform does not run a health check on the Automation Gateway. This means Itential cannot determine if it is connected to the gateway.
Property | Type | Description |
---|---|---|
type |
String | The type of health check to run. Default is Intermittent . |
frequency |
Number | Defines how often the health check should run. Measured in milliseconds (minimum = 6000 , maximum = 3600000 ). Default: 300000 . |
protocol |
String | Defines the protocol (REST , SOAP , RPC , Socket , etc.) to use to check the health of the system. Default: REST . |
uri_path |
String | The path used to check the health of Automation Gateway. This call should be a simple request for information that does not require any parameters. |
Proxy
Configure proxy settings for network environments requiring proxy connections.
Property | Type | Description |
---|---|---|
enabled |
Boolean | Defines whether or not there is a proxy. Default is false . |
host |
String | The host name of the proxy. Default: localhost . |
port |
Number | The port used to connect to the proxy. Default is 443 . |
protocol |
String | The protocol (i.e., http , https , socks4 , socks5 , etc.) used to connect to the proxy. Default: http . |
Request
Configure request handling and retry behavior.
Property | Type | Description |
---|---|---|
number_retires |
Number | Required. Defines how many times to retry a request that has aborted or reached the limit before returning an error (minimum = 0 , maximum = 20 ). Default is 3 . |
limit_retry_error |
Number | Indicates the HTTP error status code. Defines when no capacity is available and after waiting a short interval the adapter can retry the request (minimum = 0 , maximum = 1000 ). Default: 0 (zero). |
attempt_timeout |
Number | Defines how long Itential Platform should wait before aborting an attempt to connect. Measured in milliseconds (minimum = 1000 , maximum = 360000 ). Default: 5000 . |
healthcheck_on_timeout |
Boolean | Required. Defines if the system should run a health check on timeout. Default is false . If set to true , the adapter will abort the request and run a health check until it re-establishes connectivity to Automation Gateway and then it will re-attempt the request. |
archiving |
Boolean | Default is false. Archives each request and response, and corresponding metrics (i.e., wait time, connection time, Automation Gateway time) in the adapterid_results collection in MongoDB. Before enabling this property, develop an archiving strategy for cleaning up the collection in the database so that it does not become too large, especially if the responses are large. |
SSL
Configure SSL settings for secure connections.
Property | Type | Description |
---|---|---|
enabled |
Boolean | Defines whether or not SSL is enabled. Default: false . If SSL required, set to true . |
accept_invalid_cert |
Boolean | Defines whether the adapter should accept invalid certificates. Default: false . |
ca_file |
String | Defines the path name to the CA file used for SSL. |
ciphers |
String | Specifies a list of SSL ciphers to use. |
Throttle
Throttling controls the rate and volume of requests sent to Automation Gateway.
We do not recommend using adapter throttling because it can hinder the performance of your IAG instances. If you require throttling, ensure that you tune and monitor your throttle configuration so that it doesn't impact performance.
Property | Type | Description |
---|---|---|
throttle_enabled |
Boolean | Defines if the adapter should use throttling. Default: false . |
number_pronghorns |
Number | Defines if throttling is done in a single instance of Itential Platform or whether requests are being throttled across multiple instances of Itential Platform (minimum = 1 , maximum = 20 ). Default is 1 . Throttling a single instance uses an in-memory queue so there is less overhead. Throttling across multiple instances requires placing the request and queue information into a shared resource, e.g. a database, so that each instance can determine what is running and what is next to run. Throttling across multiple instances requires additional I/O overhead. |
sync_async |
String | Defines if the queue handle requests synchronously or asynchronously. |
max_in_queue |
Number | Represents the maximum number of requests Itential Platform should allow into the queue before rejecting requests (minimum = 1 , maximum = 5000 ). Default: 1000 . |
concurrent_max |
Number | Defines the number of requests that Itential Platform can send to Automation Gateway at one time (minimum = 1 , maximum = 1000 ). Default: 1 ; each request must be sent to Automation Gateway in a serial manner. |
expire_timeout |
Number | Defines the graceful timeout of the request session. After a request has completed, Itential Platform will wait additional time prior to sending the next request. Measured in milliseconds (minimum = 0 , maximum = 60000 ). Default: 0 . |
avg_runtime |
Number | Represents the approximate average of how long it takes Automation Gateway to handle each request. Measured in milliseconds (minimum = 50 , maximum = 60000 ). Default: 200 . This metric has performance implications. If the number is set too low, it puts extra burden on Itential Platform CPU and memory as the requests will continually try to run. If the number is set too high, requests may wait longer than they need to before running. The number does not need to be exact but your throttling strategy depends heavily on this number being within reason. If averages range from 50 to 250 milliseconds you might pick an average run-time somewhere in the middle so that when your Automation Gateway performance is exceptional you might run a little slower than you might like, but when it is poor you still run efficiently. |
Sample Configuration
The following JSON is a sample configuration for adapter-automation_gateway
.
{
"name": "Centos8IAGCustomerName",
"model": "@itential/adapter-automation_gateway",
"type": "Adapter",
"properties": {
"id": "Centos8IAGCustomerName",
"type": "AutomationGateway",
"brokers": [
"device",
"method"
],
"groups": [],
"properties": {
"host": "centos8-iag-customername",
"port": 8083,
"base_path": "",
"version": "v2.0",
"cache_location": "none",
"stub": false,
"protocol": "http",
"authentication": {
"auth_method": "request_token",
"username": "admin@itential",
"password": "admin",
"token": "token",
"token_user_field": "username",
"token_password_field": "password",
"token_result_field": "token",
"token_URI_path": "/api/v2.0/login",
"token_timeout": 6000,
"invalid_token_error": 401,
"auth_field": "header.headers.Authorization",
"auth_field_format": "{token}",
"token_cache": "local"
},
"healthcheck": {
"type": "intermittent",
"frequency": 300000,
"protocol": "REST",
"URI_Path": ""
},
"throttle": {
"throttle_enabled": false,
"number_pronghorns": 1,
"sync_async": "sync",
"max_in_queue": 1000,
"concurrent_max": 1,
"expire_timeout": 0,
"avg_runtime": 200
},
"request": {
"number_redirects": 0,
"number_retries": 3,
"limit_retry_error": 0,
"failover_codes": [],
"attempt_timeout": 5000,
"global_request": {
"payload": {},
"uriOptions": {},
"addlHeaders": {},
"authData": {}
},
"healthcheck_on_timeout": false,
"return_raw": false,
"archiving": false
},
"proxy": {
"enabled": false,
"host": "",
"port": 443,
"protocol": "http"
},
"ssl": {
"ecdhCurve": "",
"enabled": false,
"accept_invalid_cert": false,
"ca_file": "",
"key_file": "",
"cert_file": "",
"secure_protocol": "",
"ciphers": ""
},
"visibility": {
"module": "all",
"role": "all",
"playbook": "certified",
"script": "all",
"terraform": "all",
"collection_module": "all",
"collection_role": "all",
"nornir": "all",
"netconf": "all",
"netmiko": "all",
"grpc": "all"
},
"cluster_name": "",
"save_metric": false,
"mongo": {
"host": "",
"port": 443,
"database": "",
"username": "",
"password": "",
"replSet": ""
}
}
},
"isEncrypted": true,
"loggerProps": {
"description": "Logging",
"log_max_files": 100,
"log_max_file_size": 1048576,
"log_level": "warn",
"log_directory": "/var/log/pronghorn",
"log_filename": "pronghorn.log",
"console_level": "warn"
},
"virtual": false
}
The "playbook": "certified" in the example JSON above references the manual validation of Ansible playbooks by Itential. This was due to insufficient or inaccurate documentation of community produced playbooks or collections. Beginning with IAG 2023.1, Itential has stopped this practice as the content quality for community-produced modules and collections has reached sufficient levels that Itential’s practice of certification is no longer required.