HIRO™ comes with a Docker image of a standard Action Handler. This Action\nHandler can be configured to perform different types of actions (capabilities).\nThis guide describes how to configure the standard Action Handler via the\ndocker-compose.yml configuration file.
Before you can configure the Action Handler, make sure the following prerequisites\nare fulfilled:
\nYou have followed the instructions in Standard Docker image for Action Handlers\nto setup the Action Handler Docker container. Please make sure that the Action\nHandler correctly connects to the HIRO API.
\nYou have configured the desired capabilities in the HIRO™ SaaS system.\nThis is currently done by our SaaS team for you - please open a ticket.
\nOnce you have setup the basic Docker container for the Action Handler, and the\ncapabilities are correctly assigned in the HIRO™ system, you can proceed with\nthe steps below.
\nThe standard Action Handler comes as a Docker image. You need to use docker-compose\nto configure the Docker container for you individual use. This is done in a file\ncalled docker-compose.yml. The docker-compose tool reads this file to instantiate\nyour Docker container from the image.
For the basic steps how to create the docker-compose.yml file and run docker-compose\nplease see Standard Docker image for Action Handlers.
The Action Handler comes equipped with a default configuration for the most basic capabilities.\nTo use the default configuration, you need to set the environment variable USE_DEFAULT_AH_CONFIGS.\nThe following capabilities have a default configuration assigned:
ExecuteCommand
\nHTTPRequest
\n environment:\n USE_DEFAULT_AH_CONFIGS: ExecuteCommand,HTTPRequestWithin the docker-compose.yml file we specify an environment variable AH_CONFIG.\nThis parameter contains the configuration of the Action Handler regarding which\ncapabilities to execute, and how to execute them.
As example, the AH_CONFIG in your docker-compose.yml might look like this:
environment:\n AH_CONFIG: >\n {\n \"handlers\":[\n {\n \"name\":\"SSH Remote Handler\",\n \"capability\":\"ExecuteCommand\",\n \"implementation\":\"SSH\",\n \"exec\":\"$${command}\",\n \"user\":\"$${user}\",\n \"host\":\"$${host}\"\n },\n {\n \"name\":\"HTTP Handler\",\n \"capability\":\"HTTPRequest\",\n \"implementation\":\"HTTP\",\n \"method\":\"$${method}\",\n \"url\":\"$${url}\",\n \"params\":\"$${params}\",\n \"body\":\"$${body}\",\n \"insecure\":\"$${insecure}\"\n }\n ]\n }As you can see, the configuration specifies two handlers: SSH Remote Handler\nand HTTP Handler. Each handler is specified with a set of attributes, of which\nsome are common and some are specific to the type of implementation.
To begin with, three parameters are generic and mandatory for all capabilities:
\nname - this is a descriptive name you give your action handler
\ncapability - the identifier of the capability (action type), which the handler\nexecutes
\nimplementation - selects one of the existing implementations for executing\nactions (e.g. SSH, HTTP). See below for a list of available implementations.
\nThe further parameters depend on the chosen implementation. For instance, the HTTP\nimplementation requires parameters such as method, url and params.
Parameters from capabilities can be referenced via ${name}, so that you can make\nuse of the parameters sent by HIRO in the actions. The specific parameter values\nset by the HIRO ™ Engine through Knowledge Items (action statement) are filled\nin at run-time.
Please note: parameter references need to be escaped by $$ in the configuration\nfile. For instance, you need to write $${url}, which gets transformed into ${url}\nby docker-compose.
Two additional optional parameters were introduced with version 0.21.7 of the action handler container:
\nextract_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
\nsupply_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.
\nPlease check the Capabilities List for a list of existing capabilities.
\nAt the moment, the standard Action Handler supports the following implementations:
\nSSH
\nHTTP
\nREST
\nLOCAL
\nThe SSH implementation executes remote commands via SSH protocol. The HTTP\nimplementation executes generic HTTP(s) calls to web endpoints while the REST\nimplementation execute calls to web services conforming to the REST ActionHandler\nprotocol specification of HIRO 6. The LOCAL implementation invokes a local shell\ncommand within the docker container - this can e.g. be used to extend the standard\ndocker image with custom scripts.
\nBeyond using these implementations for plain SSH or HTTPS calls, you can also\nuse them to invoke any custom implementations. To do so, you may capsulate your\ncustom code either as a web service (with HTTPS interface) or as a console script\nthat can be invoked by the SSH action handler implementation. In order to hide the\n\"internals\" it is advised to return proper json maps on one of the standard return\nchannels and process them with the extract_fields configuration parameter so that\nthe calling KI does not have to know about the actual invocation method.
\nThe SSH handler implementation executes a command via ssh on a remote host.
\nSupported input parameters:
\n| Parameter | \nDescription | \n
|---|---|
host | \nhostname to connect to | \n
port | \nport to connect to | \n
user | \nuser to connect as | \n
password | \noptional password to use for login | \n
user_dir | \noptional path where id_rsa and known_hosts are located | \n
rsa_pass_phrase | \noptional passphrase for id_rsa | \n
connect_timeout | \ntimeout for establishing a connection | \n
Provided return values:
\n| Parameter | \nDescription | \n
|---|---|
stdout | \nstdout output of the command | \n
stderr | \nstderr output of the command | \n
exit | \nexit code of the command | \n
Configuration example:
\n{\n \"name\":\"SSH Remote Handler\",\n \"capability\":\"ExecuteCommand\",\n \"implementation\":\"SSH\",\n \"exec\":\"$${command}\",\n \"user\":\"$${user}\",\n \"host\":\"$${host}\"\n},The HTTP implementation executes an HTTPS or HTTP request to a web server.
\nSupported input parameters:
\n| Parameter | \nDescription | \n
|---|---|
method | \nhttp method, which should be executed (GET/POST/PUT/DELETE/…) | \n
url | \nurl to which the request is to be sent | \n
params | \nparameters to be included in the url | \n
body | \npayload to be sent | \n
headers | \nheaders for the request in form of 'name=value\\\\n' | \n
tls_version | \nspecify the TLS version to use. This parameter is optional - the default TLS version is | \n
username | \nusername for basic auth | \n
password | \npassword for basic auth | \n
client_certificate | \nabsolute path to the file location of an SSL client certificate file | \n
client_key | \nabsolute path to the file location of an SSL client certificate key file | \n
key_passphrase | \npassphrase for SSL client certificate file | \n
oauth | \nidentfier of a specified OAuth configuration to apply (authenticate via OAuth first, and then use a bearer token for the actual HTTPS call) | \n
insecure | \nset to \"true\" to ignore invalid https signatures (NOT RECOMMENDED) | \n
Provided return values:
\n| Parameter | \nDescription | \n
|---|---|
exec | \nexecuted http request in a format: \"${method} ${url} ${body}\" | \n
code | \nhttp response code | \n
body | \nhttp response body | \n
headers | \nhttp response headers | \n
Configuration examples:
\nHere is an example of a generic HTTP configuration, which passes all parameters through as sent from a Knowledge Item:
\n{\n \"name\":\"HTTP Handler\",\n \"capability\":\"HTTPRequest\",\n \"implementation\":\"HTTP\",\n \"method\":\"$${method}\",\n \"url\":\"$${url}\",\n \"params\":\"$${params}\",\n \"body\":\"$${body}\",\n}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.
{\n \"name\":\"My Custom REST Handler\",\n \"capability\":\"MyCustomCapability\",\n \"implementation\":\"HTTP\",\n \"supply_token\":\"hirotoken\",\n \"extract_fields\":[\"body\"],\n \"headers\":\"Authorization=Bearer ${hirotoken}\",\n \"url\":\"https://my-custom-service.local\"\n}If this service now returns a json map in the result body that looks like
\n{\n \"customresult\":\"My Custom Handler result 1\",\n \"customcode\":\"A custom handler code\"\n}then the KI using it would be able to call it using
\n customresult: LOCAL::CustomResultVar, customcode: LOCAL::CustomResultVar = action(\"MyCustomCapability\")If you want to connect to an API which requires authentication via OAuth, you can\nconfigure an OAuth endpoint, so that the HTTPS action handler retrieves a bearer\ntoken via OAuth first, before making the final HTTPS call.
\nFor example, the handler and OAuth flow configuration to use OAuth with a\nServiceNow REST API could be specified like this:
\n{\n \"handlers\": [{\n \"name\": \"HttpsWithBearer\",\n \"capability\": \"HttpsWithBearer\",\n \"implementation\": \"HTTP\",\n \"headers\": \"${headers}\",\n \"method\": \"${method}\",\n \"url\": \"${url}\",\n \"params\": \"${params}\",\n \"body\": \"${body}\",\n \"oauth\": \"${oauth}\"\n }\n ],\n \"oauths\": {\n \"service_now\": {\n \"url\": \"https://devNNNNN.service-now.com/oauth_token.do\",\n \"method\": \"post\",\n \"headers\": [\n \"content-type: application/x-www-form-urlencoded\"\n ],\n \"body\": \"grant_type=password&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>&username=<USER>&password=<PASS>\",\n \"response\": {\n \"ok_status\": 200,\n \"stop_statuses\": [401],\n \"access_token_field\": \"access_token\",\n \"expires_in_field\": \"expires_in\"\n }\n }\n }\n}In this example, the identifier of the oauth set (service_now) needs to be passed\nas parameter in the action command from the Knowledge Item.
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.
\nSupported input parameters:
\n| Parameter | \nDescription | \n
|---|---|
url | \nendpoint url to which the request is to be sent | \n
* | \nany paramter received is passed on | \n
Provided return values:
\n| Parameter | \nDescription | \n
|---|---|
exec | \nexecuted http request in a format: \"${method} ${url} ${body}\" | \n
code | \nhttp response code | \n
body | \nhttp response body | \n
Configuration example:
\n{\n \"name\":\"My Custom REST Handler\",\n \"capability\":\"MyCustomCapability\",\n \"implementation\":\"REST\",\n \"url\":\"https://my-custom-service.local\",\n}The local handler implementation executes a local shell command within the\ndocker 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:
\n| Parameter | \nDescription | \n
|---|---|
exec | \nlocal shell command to execute | \n
Provided return values:
\n| Parameter | \nDescription | \n
|---|---|
exec | \npresentation of executed command | \n
stdout | \nstdout output of the command | \n
stderr | \nstderr output of the command | \n
exit | \nexit code of the command | \n
Configuration example:
\n{\n \"name\":\"Custom Script Handler\",\n \"capability\":\"MyCustomCapability\",\n \"implementation\":\"local\",\n \"exec\":\"python3 -u /scripts/my_script.py $${param1} $${param2}\"\n},