> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.itential.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server. # Automation Gateway adapter > Reference for configuring the adapter-automation_gateway adapter, including adapter properties, authentication, healthcheck, SSL, throttle, and a sample configuration. The Automation Gateway adapter integrates Gateway with Itential Platform through the Gateway 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 Gateway 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](/adapters/configure/service-instance-configuration/properties/mongo-properties). ```json { "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 } ``` **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 Gateway 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.