• Services
  • Migration Topics
  • Integration
    • Standard ActionHandlers
      • How to configure capabilities in the standard Action Handler (Docker image)
      • How to extend the Action Handler Docker image
      • On-premise Action Handler Installation Guide (Docker Image)
      • Troubleshooting Guide for HIRO™ Action Handlers
    • ServiceNow
    • SAP
    • Jira
    • Email
    • CSV
    • Approval
    • Introduction to ActionHandlers and Connectors
  • Concepts
  • Best Practices
  • Api

Introduction

ActionHandlers are integration components of the HIRO system. They are used to invoke actions on target systems. The ActionHandler establishes a websocket connection with the HIRO Action-API. An ActionHandler can be deployed either on our SaaS platform or can be hosted on a machine in your network. The latter has the advantage of not needing to open inbound ports on firewall. This document is for our customers who choose the latter.

The installation requires three steps:

  • Setting up docker

  • Defining docker composition (docker-compose.yml)

  • Starting the ActionHandler container

Setting up docker

The HIRO standard Action Handlers (SSH and HTTP) are provided using a docker image. This image must be mounted in a maschine in your network running docker. For general information on docker, please refer to the help pages on DockerHub. We assume you’ve installed docker and docker-compose. You can verify by checking the versions:

$ docker -v
Docker version xx.xx.xx, build xxxxxxxxxx
$ docker-compose -v
docker-compose version x.xx.x, build xxxxxxxx

Linux based container images

All arago docker images are Linux based. The Docker image is published on our DockerHub repository. Please ensure that your docker installation can run linux based images. You can confirm by pulling the latest image and check for error messages.

docker pull arago/hiro-actionhandler:latest

In case you are presented with an error message about Linux images not usable on your platform, please refer to the DockerHub help pages and adjust your installation.

Defining docker composition (docker-compose.yml)

The docker composition defines which image and how the container is started. It is defined in a configuration file in YAML format and holds the information about for your docker image, the HIRO instance and the type of actions you seek to execute.

Sample docker-compose.yml
version: "3.7"
services:
  actionhandler:
    image: arago/hiro-actionhandler:latest # Please update version number to the most recent tagged version
    container_name: actionhandler
    env_file: ~/[path to your environment file]/config.env
    restart: always
    volumes: #required for SSH only
      - type: bind
        source: [absolute path]/[private key file]
        target: /home/hiro/.ssh/id_rsa
    environment:
      AH_CONFIG: >
        {
          "handlers": [
            {
              "name": "SSH Remote Handler",
              "capability": "ExecuteCommand",
              "implementation": "SSH",
              "exec": "$${command}",
              "user": "$${user}",
              "host": "$${host}"
            },
            {
              "name": "HTTPHandler",
              "capability": "HTTPRequest",
              "implementation": "HTTP",
              "url": "$${url}",
              "params": "$${params}",
              "headers": "$${headers}",
              "method": "$${method}",
              "body": "$${body}",
              "insecure": "$${allow_insecure_https}"
            }
          ]
        }

The next sections walk you through the required adjustments: We will pass an environment variable file with HIRO credentials, mount the SSH private key and pass environment (when required) and define the Action Handler configuration map.

Creating environment variable file (config.env)

You need to create an ActionHandler environment variable file for the docker image, typically named config.env. This file holds the credentials for your HIRO instance.

Sample config.env
HIRO_USER=XXXXXXX
HIRO_PASS=XXXXXXX
HIRO_EXTERNAL_USER=XXXXXXX
HIRO_EXTERNAL_PASS=XXXXXXX

Each ActionHandler should have a dedicated service user account for the respective HaaS instance. In case you do not have the credentials ready, please login to the arago account management application Arago ID, navigate to Member tab and search for users named 'actionhandler'.

Search User

If a dedicated ActionHandler user does not exist for your haas-instance yet, please contact your organization admin. Make a note of the username and password and enter them in the environment variable file for HIRO_USER and HIRO_PASS. You can change the password by clicking the options icon and select Edit Profile. In case of questions, you can also contact the HIRO Support.

The HIRO_EXTERNAL_USER and HIRO_EXTERNAL_PASS environment variables are optional if the "supply_token" functionality is required and the token passed to the actual handler should use a different user account than the ActionHandler itself.

Mounting RSA private key (for SSH only)

If you want to invoke SSH commands using the ActionHandler, you need to mount an RSA private key into the container and exchange the public key with the target system. The key needs to be in pkcs8 format and should not have a passphrase. You can generate a new key pair with the following command:

ssh-keygen -m pkcs8

Save the key pair to the server running docker and set the source attributes in the docker composition to the location of the private key- and cert-file. Make sure the files are readable for the ActionHandler (by default, the ActionHandler is run as user hiro with id 1000). Do not forget to add the content of the generated public key into ~/.ssh/authorized_keys on your the target system.

Please note: From a container perspective, even the local host is a remote target system, so you should be following the same steps. However, you might find some shortcuts in the DockerHub help pages for network configuration.

Action Handler configuration map (AH_CONFIG)

Your connector needs a configuration of which actions or capabilities to process and how to execute them. This is configured in a configuration variable called AH_CONFIG.

Please refer to How to configure capabilities in the standard Action Handler (Docker image) for details on the configuration map.

Starting the ActionHandler container

Once the composition is defined, you can start the ActionHandler docker container by issuing the following command:

docker-compose up

Please make sure you are issuing this command from the same directory your docker-compose.yml file is located in. Upon sucess, you should see the following log entries:

Sample log entris after successfull composition
[...]
Creating network "docker_default" with the default driver
Creating actionhandler ... done
Attaching to actionhandler
[...]
actionhandler    | {"time":"...","severity":"info","message":"Authenticating...","metadata":{}}
actionhandler    | {"time":"...","severity":"info","message":"Successfully authenticated.","metadata":{}}
[...]
actionhandler    | {"time":"...","severity":"info","message":"Connected to core.arago.co using http","metadata":{}}
actionhandler    | {"time":"...","severity":"info","message":"Upgrading connection...","metadata":{}}
actionhandler    | {"time":"...","severity":"info","message":"WebSocket upgrade succeeded.","metadata":{}}
actionhandler    | {"time":"...","severity":"info","message":"[ActionHandler] New ActionWS status: :ready","metadata":{}}
[...]

In case of generic docker problems, please refer to the DockerHub help pages. On problems related to the ActionHandler docker image, please contact HIRO Support.

The command above composes a docker container attached to your current console. In other words: If you close the console, the container will be terminated. To compose a detached container, please issue the following command:

docker-compose up --detach

More information on attached and detached containers and their lifespan can be found on the DockerHub help pages.

Sample KIs for testing

You can test your ActionHandler by executing the follow KIs from HIRO™:

Sample KI for a HTTP request
on
  ogit/_id
when
  ProcessIssue == "TestHTTPRequest"
do
  code: LOCAL::STATUS,
  body: LOCAL::RESULT = action(
	capability: "HTTPRequest",
	params: "format=json",
	url: "https://api64.ipify.org/",
	timeout: "10"
  )
  if LOCAL::STATUS == "200" then
    log("SUCCESS: Your IP adress is ${LOCAL::RESULT}")
  else
    log("ERROR ${LOCAL::STATUS}: ${LOCAL::RESULT}")
  end
  delete(ProcessIssue)
Expected HIRO Engine log
action action executed: GET https://api64.ipify.org/?format=json
info
action arguments: {"Arguments":{"params":"format=json","timeout":"10","url":"https://api64.ipify.org/"},"Capability":"HTTPRequest"}, results: {"body":"{\"ip\":\"52.30.30.78\"}","code":200,"exec":"GET https://api64.ipify.org/?format=json ","headers":"{\"Connection\":\"keep-alive\",\"Content-Length\":\"20\",\"Content-Type\":\"application/json\",\"Date\":\"Mon, 04 Oct 2021 12:41:42 GMT\",\"Server\":\"nginx/1.19.7\",\"Vary\":\"Origin\"}"}
debug
log SUCCESS: Your IP adress is xxx.xxx.xxx.xxx
info
Sample KI for a SSH command
on
  ogit/_id
when
  ProcessIssue == "TestSSH"
do
  stdout: LOCAL::OUTPUT,
  stderr: LOCAL::ERROR,
  exit: LOCAL::SYSTEMRC = action("ExecuteCommand", command: "echo Hello World", host: "{ip of your target system}", user: "{user for your target system}", timeout: "20")
  if LOCAL::SYSTEMRC == "0" then
    log("SUCCESS: ${LOCAL::OUTPUT}")
  else
    log("ERROR ${LOCAL::SYSTEMRC}: ${LOCAL::ERROR}")
  end
  delete(ProcessIssue)