How to configure Action Handler capabilities

Services
Migration Topics
Integration

Capabilities
WinRM
Standard ActionHandlers

How to configure Action Handler capabilities
How to extend the Action Handler Docker image
On-premise Action Handler Installation Guide
Troubleshooting Guide for HIRO™ Action Handlers

ServiceNow
Jira
Email
SAP
Approval
CSV
Introduction to ActionHandlers and Connectors

Concepts
Best Practices
Api

Table of Contents

Introduction
Prerequisites
Defining docker composition
Using default capability configuration
Setting custom capability configuration
Special Parameters
Available capabilities
Available implementations

Introduction

HIRO™ comes with a Docker image of a standard Action Handler. This Action Handler can be configured to perform different types of actions (capabilities). This guide describes how to configure the standard Action Handler via the docker-compose.yml configuration file.

Prerequisites

Before you can configure the Action Handler, make sure the following prerequisites are fulfilled:

You have followed the instructions in Standard Docker image for Action Handlers to setup the Action Handler Docker container. Please make sure that the Action Handler correctly connects to the HIRO API.
You have configured the desired capabilities in the HIRO™ SaaS system. This is currently done by our SaaS team for you - please open a ticket.

Once you have setup the basic Docker container for the Action Handler, and the capabilities are correctly assigned in the HIRO™ system, you can proceed with the steps below.

Defining docker composition

The standard Action Handler comes as a Docker image. You need to use docker-compose to configure the Docker container for you individual use. This is done in a file called docker-compose.yml. The docker-compose tool reads this file to instantiate your Docker container from the image.

For the basic steps how to create the docker-compose.yml file and run docker-compose please see Standard Docker image for Action Handlers.

Using default capability configuration

The Action Handler comes equipped with a default configuration for the most basic capabilities. To use the default configuration, you need to set the environment variable USE_DEFAULT_AH_CONFIGS. The following capabilities have a default configuration assigned:

ExecuteCommand
HTTPRequest

Using default configuration in docker-compose.yml

    environment:
      USE_DEFAULT_AH_CONFIGS: ExecuteCommand,HTTPRequest

Setting custom capability configuration

Within the docker-compose.yml file we specify an environment variable AH_CONFIG. This parameter contains the configuration of the Action Handler regarding which capabilities to execute, and how to execute them.

As example, the AH_CONFIG in your docker-compose.yml might look like this:

  environment:
    AH_CONFIG: >
      {
        "handlers":[
          {
            "name":"SSH Remote Handler",
            "capability":"ExecuteCommand",
            "implementation":"SSH",
            "exec":"$${command}",
            "user":"$${user}",
            "host":"$${host}"
          },
          {
            "name":"HTTP Handler",
            "capability":"HTTPRequest",
            "implementation":"HTTP",
            "method":"$${method}",
            "url":"$${url}",
            "params":"$${params}",
            "body":"$${body}",
            "insecure":"$${insecure}"
          }
        ]
      }

As you can see, the configuration specifies two handlers: SSH Remote Handler and HTTP Handler. Each handler is specified with a set of attributes, of which some are common and some are specific to the type of implementation.

To begin with, three parameters are generic and mandatory for all capabilities:

name - this is a descriptive name you give your action handler
capability - the identifier of the capability (action type), which the handler executes
implementation - selects one of the existing implementations for executing actions (e.g. SSH, HTTP). See below for a list of available implementations.

The further parameters depend on the chosen implementation. For instance, the HTTP implementation requires parameters such as method, url and params.

Parameters from capabilities can be referenced via ${name}, so that you can make use of the parameters sent by HIRO in the actions. The specific parameter values set by the HIRO ™ Engine through Knowledge Items (action statement) are filled in at run-time.

Please note: parameter references need to be escaped by $$ in the configuration file. For instance, you need to write $${url}, which gets transformed into ${url} by docker-compose.

Special Parameters

Two additional optional parameters were introduced with version 0.21.7 of the action handler container:

extract_fields can be used to specify if any of the return parameter fields should be processed by a JSON parser and the result be added to the result parameter set. A typical example for this would be "body" for an HTTP actionhandler returning a JSON map with multiple result fields which should be directly accessible from the calling KI
supply_token can be used to specify a parameter name which will be internally added before processing. The value of that parameter will be a freshly generated graph token that can be passed along to external handlers to allow access back to the graph.

Available capabilities

Please check the Capabilities List for a list of existing capabilities.

Available implementations

At the moment, the standard Action Handler supports the following implementations:

SSH
HTTP
REST
LOCAL

The SSH implementation executes remote commands via SSH protocol. The HTTP implementation executes generic HTTP(s) calls to web endpoints while the REST implementation execute calls to web services conforming to the REST ActionHandler protocol specification of HIRO 6. The LOCAL implementation invokes a local shell command within the docker container - this can e.g. be used to extend the standard docker image with custom scripts.

Beyond using these implementations for plain SSH or HTTPS calls, you can also use them to invoke any custom implementations. To do so, you may capsulate your custom code either as a web service (with HTTPS interface) or as a console script that can be invoked by the SSH action handler implementation. In order to hide the "internals" it is advised to return proper json maps on one of the standard return channels and process them with the extract_fields configuration parameter so that the calling KI does not have to know about the actual invocation method.

SSH Handler Implementation

The SSH handler implementation executes a command via ssh on a remote host.

Supported input parameters:

Table 1. Supported Parameters
Parameter	Description
host	hostname to connect to
port	port to connect to
user	user to connect as
password	optional password to use for login
user_dir	optional path where id_rsa and known_hosts are located
rsa_pass_phrase	optional passphrase for id_rsa
connect_timeout	timeout for establishing a connection

Provided return values:

Table 2. Return Values
Parameter	Description
stdout	stdout output of the command
stderr	stderr output of the command
exit	exit code of the command

Configuration example:

Sample SSH Handler Configuration

{
  "name":"SSH Remote Handler",
  "capability":"ExecuteCommand",
  "implementation":"SSH",
  "exec":"$${command}",
  "user":"$${user}",
  "host":"$${host}"
},

HTTP Handler Implementation

The HTTP implementation executes an HTTPS or HTTP request to a web server.

Supported input parameters:

Table 3. Supported Parameters
Parameter	Description
method	http method, which should be executed (GET/POST/PUT/DELETE/…)
url	url to which the request is to be sent
params	parameters to be included in the url
body	payload to be sent
headers	headers for the request in form of 'name=value\\n'
tls_version	specify the TLS version to use. This parameter is optional - the default TLS version is `1.3`.
username	username for basic auth
password	password for basic auth
client_certificate	absolute path to the file location of an SSL client certificate file
client_key	absolute path to the file location of an SSL client certificate key file
key_passphrase	passphrase for SSL client certificate file
oauth	identfier of a specified OAuth configuration to apply (authenticate via OAuth first, and then use a bearer token for the actual HTTPS call)
insecure	set to "true" to ignore invalid https signatures (NOT RECOMMENDED)

Provided return values:

Table 4. Return Values
Parameter	Description
exec	executed http request in a format: "${method} ${url} ${body}"
code	http response code
body	http response body
headers	http response headers

Configuration examples:

Here is an example of a generic HTTP configuration, which passes all parameters through as sent from a Knowledge Item:

Sample HTTP Handler Configuration

{
  "name":"HTTP Handler",
  "capability":"HTTPRequest",
  "implementation":"HTTP",
  "method":"$${method}",
  "url":"$${url}",
  "params":"$${params}",
  "body":"$${body}",
}

The next example shows how to use a specific URL to invoke a web service, using the supply_token option to pass on a static authentication token, and extracting fields from the returned response body.

Sample custom HTTP Endpoint requiring token and doing result parameter extraction

{
  "name":"My Custom REST Handler",
  "capability":"MyCustomCapability",
  "implementation":"HTTP",
  "supply_token":"hirotoken",
  "extract_fields":["body"],
  "headers":"Authorization=Bearer ${hirotoken}",
  "url":"https://my-custom-service.local"
}

If this service now returns a json map in the result body that looks like

{
  "customresult":"My Custom Handler result 1",
  "customcode":"A custom handler code"
}

then the KI using it would be able to call it using

  customresult: LOCAL::CustomResultVar, customcode: LOCAL::CustomResultVar = action("MyCustomCapability")

If you want to connect to an API which requires authentication via OAuth, you can configure an OAuth endpoint, so that the HTTPS action handler retrieves a bearer token via OAuth first, before making the final HTTPS call.

For example, the handler and OAuth flow configuration to use OAuth with a ServiceNow REST API could be specified like this:

{
    "handlers": [{
            "name": "HttpsWithBearer",
            "capability": "HttpsWithBearer",
            "implementation": "HTTP",
            "headers": "${headers}",
            "method": "${method}",
            "url": "${url}",
            "params": "${params}",
            "body": "${body}",
            "oauth": "${oauth}"
        }
    ],
    "oauths": {
        "service_now": {
            "url": "https://devNNNNN.service-now.com/oauth_token.do",
            "method": "post",
            "headers": [
                "content-type: application/x-www-form-urlencoded"
            ],
            "body": "grant_type=password&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>&username=<USER>&password=<PASS>",
            "response": {
                "ok_status": 200,
                "stop_statuses": [401],
                "access_token_field": "access_token",
                "expires_in_field": "expires_in"
            }
        }
    }
}

In this example, the identifier of the oauth set (service_now) needs to be passed as parameter in the action command from the Knowledge Item.

REST Handler Implementation

The REST handler is a specialized version of the HTTP handler only for use with servers implementing the HIRO 6 REST ActionHandler protocol. With this ActionHandler, all parameters included in the call are passed on to the destination. So there cannot, but also does not need to be any parameter definition in the handler section.

Supported input parameters:

Table 5. Supported Parameters
Parameter	Description
url	endpoint url to which the request is to be sent
*	any paramter received is passed on

Provided return values:

Table 6. Return Values
Parameter	Description
exec	executed http request in a format: "${method} ${url} ${body}"
code	http response code
body	http response body

Configuration example:

Sample REST handler configuration

{
  "name":"My Custom REST Handler",
  "capability":"MyCustomCapability",
  "implementation":"REST",
  "url":"https://my-custom-service.local",
}

LOCAL Implementation

The local handler implementation executes a local shell command within the docker container. It is recommended to use this implementation only if you extend the docker image by additional layers. For instance, you may add an additional docker layer with a script file, which gets executed via the local implementation.

Supported input parameters:

Table 7. Supported Parameters
Parameter	Description
exec	local shell command to execute

Provided return values:

Table 8. Return Values
Parameter	Description
exec	presentation of executed command
stdout	stdout output of the command
stderr	stderr output of the command
exit	exit code of the command

Configuration example:

Sample LOCAL Handler Configuration

{
  "name":"Custom Script Handler",
  "capability":"MyCustomCapability",
  "implementation":"local",
  "exec":"python3 -u /scripts/my_script.py $${param1} $${param2}"
},