Automation Gateway

  • Updated on Feb 6, 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.

Related Reading: Itential Opensource

Itential Platform Service Instance Configurations

Adapter Properties

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 is 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 is v2.0.
authentication Object Required. Defines the properties used for authentication.
stub Boolean Optional.
protocol String Optional. 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 Optional. 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 Optional. 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

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 set to -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 is 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

The following settings are currently supported.

  • None - Not recommended. Itential Platform will not run a check on Automation Gateway. Consequently, it is unable to determine if Itential can connect with Automation Gateway.
  • Startup - Itential will check for connectivity when the adapter initially comes up, but it will not check afterwards.
  • Intermittent - The adapter will check connectivity to Automation Gateway at the frequency defined in the frequency property
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 is 300000.
protocol String Defines the protocol (REST, SOAP, RPC, Socket, etc.) to use to check the health of the system. Default is 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.

Throttle

Property Type Description
throttle_enabled Boolean Defines if the adapter should use throttling. Default is 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 is 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 is 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 is 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 is 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.

Request

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 Optional. 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 is set to 0 (zero).
attempt_timeout Number Optional. Defines how long Itential Platform should wait before aborting an attempt to connect. Measured in milliseconds (minimum = 1000, maximum = 360000). Default is 5000.
healthcheck_on_timeout Boolean 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 Optional. 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.

Proxy

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 is 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 is http.

SSL

Property Type Description
enabled Boolean Defines whether or not SSL is enabled. Default is false. If SSL required, set to true.
accept_invalid_cert Boolean Defines whether the adapter should accept invalid certificates. Default is 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.

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
}
Note:

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.