For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Open sourceSupportFAQsDocs Home
  • Introduction
    • Overview
    • Retired adapters
      • Overview
      • SSL/TLS
      • Throttling
      • Headers
      • Add dynamic headers
      • Add query parameters
      • Update adapter configuration
        • Automation Gateway
        • Cisco NSO
        • SQL
LogoLogo
Open sourceSupportFAQsDocs Home
On this page
  • Adapter properties
  • Authentication
  • Healthcheck
  • Proxy
  • Request
  • SSL
  • Throttle
  • Sample configuration
ConfigureReference

Automation Gateway adapter

Was this page helpful?
Previous

NSO adapter

Next
Built with

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.

PropertyTypeDescription
hostStringRequired. The hostname of the Automation Gateway adapter.
portNumberRequired. The port on which to connect to the adapter. Default: 443.
choosepathStringControls 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_pathStringA 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.
versionStringRequired. The current API version the adapter integrates with. Default: v2.0.
authenticationObjectRequired. Defines the properties used for authentication.
stubBooleanDefines whether the stub should run instead of making calls to Automation Gateway. Useful during basic testing. Default: false.
protocolStringNotifies the adapter whether to use HTTP or HTTPS. Default: http.
healthcheckObjectRequired. Defines the health check settings currently supported.
throttleObjectDefines the properties used to throttle requests to Automation Gateway.
requestObjectDefines the properties used to handle requests and responses.
proxyObjectDefines the properties used to handle proxy connections.
sslObjectRequired. Defines the properties to use SSL authentication with Automation Gateway.
strip_escapesBooleanStrips 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.

PropertyTypeDescription
auth_methodStringThe authentication method used in requests. Valid methods: request_token (default), static_token, and no_authentication.
usernameStringThe username to authenticate with Automation Gateway on every request or when pulling a token for subsequent requests.
passwordStringThe 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}.
tokenStringA static token that can be used on all requests.
token_user_fieldStringThe field in the token request where the username credential should be provided.
token_password_fieldStringThe field in the token request where the password credential should be provided.
token_result_fieldStringThe field in the token response where the actual token will be.
token_URI_pathStringThe API path used to retrieve a token.
token_timeoutNumberHow 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_errorNumberThe HTTP error received when a token is invalid. Notifies the adapter to pull a new token and retry the request. Default: 401.
auth_fieldStringThe header field in which to place the token.
auth_field_formatStringThe 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.
PropertyTypeDescription
typeStringThe type of health check to run. Default: Intermittent.
frequencyNumberHow often the health check should run, in milliseconds. Minimum: 6000, maximum: 3600000. Default: 300000.
protocolStringThe protocol (REST, SOAP, RPC, Socket, etc.) to use to check the health of the system. Default: REST.
uri_pathStringThe 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.

PropertyTypeDescription
enabledBooleanDefines whether there is a proxy. Default: false.
hostStringThe host name of the proxy. Default: localhost.
portNumberThe port used to connect to the proxy. Default: 443.
protocolStringThe protocol (http, https, socks4, socks5, etc.) used to connect to the proxy. Default: http.

Request

Configure request handling and retry behavior.

PropertyTypeDescription
number_retriesNumberRequired. 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_errorNumberThe 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_timeoutNumberHow long Itential Platform should wait before aborting an attempt to connect, in milliseconds. Minimum: 1000, maximum: 360000. Default: 5000.
healthcheck_on_timeoutBooleanRequired. 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.
archivingBooleanArchives 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.

PropertyTypeDescription
enabledBooleanDefines whether SSL is enabled. Default: false. Set to true if SSL is required.
accept_invalid_certBooleanDefines whether the adapter should accept invalid certificates. Default: false.
ca_fileStringThe path name to the CA file used for SSL.
ciphersStringA 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.

PropertyTypeDescription
throttle_enabledBooleanDefines if the adapter should use throttling. Default: false.
number_pronghornsNumberDefines 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_asyncStringDefines whether the queue handles requests synchronously or asynchronously.
max_in_queueNumberThe maximum number of requests Itential Platform should allow into the queue before rejecting requests. Minimum: 1, maximum: 5000. Default: 1000.
concurrent_maxNumberThe 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_timeoutNumberThe 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_runtimeNumberThe 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.