Automation Gateway

  • Updated on Sep 24, 2025
  • Published on Jun 19, 2023
Prev Next

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.

Throttling not recommended

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
}
Deprecated manual validation for Ansible playbook certification

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.

Related topics

Itential Platform Service Instance Configurations