Automation Gateway adapter

The Automation Gateway adapter integrates IAG with Itential Platform through the IAG API. Use this reference 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: `443`.
`choosepath`	String	Controls which path to use for an API call. The Endpoint Configuration for the adapter must have an array of `entitypaths` to use `choosepath`. For the gateway adapter, `choosepath` can be empty or set to `v0` to work in default mode. To honor the `base_path` configuration, set `choosepath` to `v1`.
`base_path`	String	A base path that appears in most or all API calls. You can override the base path on individual actions in the Endpoint Configuration for the adapter. Using `base_path` makes it easier to maintain the adapter when the API path changes — you only need to update this property rather than every `entitypath` in the Endpoint Configuration. Example: For `http://xyz.abc.com:8080/api/rest/v1/abc`, the base path is `/api/rest`.
`version`	String	Required. 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: `false`.
`protocol`	String	Notifies the adapter whether to use HTTP or HTTPS. Default: `http`.
`healthcheck`	Object	Required. Defines the 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 proxy connections.
`ssl`	Object	Required. Defines the properties to use SSL authentication with Automation Gateway.
`strip_escapes`	Boolean	Strips out additional backslashes from all API calls. Default: `false`. Enable by setting to `true`. The default setting is recommended unless extra escape characters (backslashes) are being added to API calls that should be removed.

Authentication

Configure authentication methods for secure communication with Automation Gateway.

Property	Type	Description
`auth_method`	String	The authentication method used in requests. Valid methods: `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 for subsequent requests.
`password`	String	The password to authenticate with Automation Gateway on every request or when pulling a token. If retrieved through an encrypt password call, use the exact return value including `{code}`.
`token`	String	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	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	How long a token is valid, in milliseconds. Once a dynamic token is no longer valid, Itential Platform pulls a new token. Default: `-1` (pulls a token on every request). Maximum: `3600000`.
`invalid_token_error`	Number	The HTTP error received when a token is invalid. Notifies the adapter to pull a new token and retry the request. Default: `401`.
`auth_field`	String	The header field in which to place the token.
`auth_field_format`	String	The format used to pass the authentication variables.

Healthcheck

Use healthchecks to monitor your adapter’s connectivity to 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 provides simplicity and prevents unnecessary errors that can occur when a health check fails but Automation Gateway becomes available before the next scheduled check.
Intermittent — The adapter checks connectivity to Automation Gateway at the frequency defined by the frequency property.
None (not recommended) — Itential Platform does not run a health check on Automation Gateway and cannot determine if it is connected to the gateway.

Property	Type	Description
`type`	String	The type of health check to run. Default: `Intermittent`.
`frequency`	Number	How often the health check should run, in milliseconds. Minimum: `6000`, maximum: `3600000`. Default: `300000`.
`protocol`	String	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 there is a proxy. Default: `false`.
`host`	String	The host name of the proxy. Default: `localhost`.
`port`	Number	The port used to connect to the proxy. Default: `443`.
`protocol`	String	The protocol (`http`, `https`, `socks4`, `socks5`, etc.) used to connect to the proxy. Default: `http`.

Request

Configure request handling and retry behavior.

Property	Type	Description
`number_retries`	Number	Required. How many times to retry a request that has aborted or reached the limit before returning an error. Minimum: `0`, maximum: `20`. Default: `3`.
`limit_retry_error`	Number	The HTTP error status code indicating no capacity is available. After waiting a short interval, the adapter can retry the request. Minimum: `0`, maximum: `1000`. Default: `0`.
`attempt_timeout`	Number	How long Itential Platform should wait before aborting an attempt to connect, 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: `false`. If `true`, the adapter aborts the request, runs a health check until it re-establishes connectivity to Automation Gateway, then re-attempts the request.
`archiving`	Boolean	Archives each request and response, and corresponding metrics (wait time, connection time, Automation Gateway time) in the `adapterid_results` MongoDB collection. Default: `false`. Before enabling, develop an archiving strategy to prevent the collection from growing too large, especially if responses are large.

SSL

Configure SSL settings for secure connections.

Property	Type	Description
`enabled`	Boolean	Defines whether SSL is enabled. Default: `false`. Set to `true` if SSL is required.
`accept_invalid_cert`	Boolean	Defines whether the adapter should accept invalid certificates. Default: `false`.
`ca_file`	String	The path name to the CA file used for SSL.
`ciphers`	String	A list of SSL ciphers to use.

Throttle

Throttling controls the rate and volume of requests sent to Automation Gateway.

Adapter throttling is not recommended because it can hinder the performance of your IAG instances. If you require throttling, tune and monitor your throttle configuration to avoid performance impact.

Property	Type	Description
`throttle_enabled`	Boolean	Defines if the adapter should use throttling. Default: `false`.
`number_pronghorns`	Number	Defines whether throttling is done in a single instance of Itential Platform or across multiple instances. Minimum: `1`, maximum: `20`. Default: `1`. Single-instance throttling uses an in-memory queue with less overhead. Multi-instance throttling requires placing request and queue information into a shared resource (such as a database), adding I/O overhead.
`sync_async`	String	Defines whether the queue handles requests synchronously or asynchronously.
`max_in_queue`	Number	The maximum number of requests Itential Platform should allow into the queue before rejecting requests. Minimum: `1`, maximum: `5000`. Default: `1000`.
`concurrent_max`	Number	The number of requests that Itential Platform can send to Automation Gateway at one time. Minimum: `1`, maximum: `1000`. Default: `1` (requests must be sent serially).
`expire_timeout`	Number	The graceful timeout of the request session. After a request completes, Itential Platform waits this additional time before sending the next request, in milliseconds. Minimum: `0`, maximum: `60000`. Default: `0`.
`avg_runtime`	Number	The approximate average time it takes Automation Gateway to handle each request, in milliseconds. Minimum: `50`, maximum: `60000`. Default: `200`. If set too low, it puts extra burden on Itential Platform CPU and memory. If set too high, requests may wait longer than necessary. The number does not need to be exact, but your throttling strategy depends heavily on this value being within reason.

Sample configuration

The following JSON is a sample configuration for adapter-automation_gateway.

For more information on configuring MongoDB properties, see Mongo property definitions.

1 {
2   "name": "Centos8IAGCustomerName",
3   "model": "@itential/adapter-automation_gateway",
4   "type": "Adapter",
5   "properties": {
6     "id": "Centos8IAGCustomerName",
7     "type": "AutomationGateway",
8     "brokers": [
9       "device",
10       "method"
11     ],
12     "groups": [],
13     "properties": {
14       "host": "centos8-iag-customername",
15       "port": 8083,
16       "base_path": "",
17       "version": "v2.0",
18       "cache_location": "none",
19       "stub": false,
20       "protocol": "http",
21       "authentication": {
22         "auth_method": "request_token",
23         "username": "admin@itential",
24         "password": "admin",
25         "token": "token",
26         "token_user_field": "username",
27         "token_password_field": "password",
28         "token_result_field": "token",
29         "token_URI_path": "/api/v2.0/login",
30         "token_timeout": 6000,
31         "invalid_token_error": 401,
32         "auth_field": "header.headers.Authorization",
33         "auth_field_format": "{token}",
34         "token_cache": "local"
35       },
36       "healthcheck": {
37         "type": "intermittent",
38         "frequency": 300000,
39         "protocol": "REST",
40         "URI_Path": ""
41       },
42       "throttle": {
43         "throttle_enabled": false,
44         "number_pronghorns": 1,
45         "sync_async": "sync",
46         "max_in_queue": 1000,
47         "concurrent_max": 1,
48         "expire_timeout": 0,
49         "avg_runtime": 200
50       },
51       "request": {
52         "number_redirects": 0,
53         "number_retries": 3,
54         "limit_retry_error": 0,
55         "failover_codes": [],
56         "attempt_timeout": 5000,
57         "global_request": {
58           "payload": {},
59           "uriOptions": {},
60           "addlHeaders": {},
61           "authData": {}
62         },
63         "healthcheck_on_timeout": false,
64         "return_raw": false,
65         "archiving": false
66       },
67       "proxy": {
68         "enabled": false,
69         "host": "",
70         "port": 443,
71         "protocol": "http"
72       },
73       "ssl": {
74         "ecdhCurve": "",
75         "enabled": false,
76         "accept_invalid_cert": false,
77         "ca_file": "",
78         "key_file": "",
79         "cert_file": "",
80         "secure_protocol": "",
81         "ciphers": ""
82       },
83       "visibility": {
84         "module": "all",
85         "role": "all",
86         "playbook": "certified",
87         "script": "all",
88         "terraform": "all",
89         "collection_module": "all",
90         "collection_role": "all",
91         "nornir": "all",
92         "netconf": "all",
93         "netmiko": "all",
94         "grpc": "all"
95       },
96       "cluster_name": "",
97       "save_metric": false,
98       "mongo": {
99         "host": "",
100         "port": 443,
101         "database": "",
102         "username": "",
103         "password": "",
104         "replSet": ""
105       }
106     }
107   },
108   "isEncrypted": true,
109   "loggerProps": {
110     "description": "Logging",
111     "log_max_files": 100,
112     "log_max_file_size": 1048576,
113     "log_level": "warn",
114     "log_directory": "/var/log/pronghorn",
115     "log_filename": "pronghorn.log",
116     "console_level": "warn"
117   },
118   "virtual": false
119 }

Deprecated: manual validation for Ansible playbook certification

The "playbook": "certified" value in the sample configuration above references the manual validation of Ansible playbooks by Itential. Beginning with IAG 2023.1, Itential has stopped this practice — community-produced module and collection content quality has reached sufficient levels that Itential’s certification practice is no longer required.