• Services
  • Migration Topics
  • Integration
  • Concepts
  • Best Practices
  • Api
    • DomainObjectApi
    • Changelog
    • HIRO API Overview
    • HIRO Audit API
    • HIRO Graph - Gremlin Query
    • HIRO Graph Action API
    • HIRO Graph Auth API
    • HIRO Graph List API
    • HIRO Graph WebSocket API
    • Refresh Token

The Action API has been introduced to separate the deployment of action handlers from the HIRO™ Engine. The new Action API uses the graph as a "broker" between the Engine and action handlers and all the connections are now outbound (from customer network perspective) to the HIRO SaaS system. This enables customers to deploy Action Handlers on premises and make an outbound connection to the Action API without opening an inbound port.

Also, the action data is persisted in the SaaS infrastructure, so crashes or interruptions of network connectivity should not result in failed or repeated execution of the same command.

System Architecture

actionhandler generic overview
Figure 1. Action API System Architecture

Terminology

Action Handler

An Action Handler is a separate component that has the capability to perform actions on the customer’s target systems. Depending on the requirements and the type of Action Handler, it can now be either deployed on the HIRO™ SaaS platform itself or on the premises of the customer.

Capability

A capability describes a specific type of action (e.g. "ExecuteCommand") and the mandatory and optional parameters (e.g. "Command", "Timeout" or "Host"). Capabilities are meant to be defined globally and should be considered as kind of a "feature contract" between Knowledge Item writers and Action Handler implementations. The semantics of a capability and its parameters should be the same across all installations so that KIs making use of Action Handlers will continue to work even though underlying implementations of the handlers might be completely different.

Applicability

An applicability binds a global capability to a specific Action Handler instance running alongside a single engine. It can optionally supply additional parameters to the actual handler implementation not part of the capability definition but these will not be visible or directly accessible to KI writers. The applicability can limit the scope on which vertices this specific handler-binding will be available.

For example an applicability could specify that an SSH based Action Handler provides the capability ExecuteCommand but only on linux machines (represented in the environment model as vertices of the type ogit/MARS/Machine with a machineClass attribute "Linux") which have a "SSHKeyID" attribute as well. The SSHKeyID would then be added to the parameter set sent to the action handler implicitly without KI writers needing to care about that.

Interface / API Definitions

(GET) / capabilities

The Action Handler application can request the list of registered capabilities with their parameter list from the global registry.

Response Example

{
  "ExecuteCommand": {
    "description": "this one executes commands",
    "mandatoryParameters": {
      "command": {
        "description": "command to execute"
        },
    "host": {
      "description": "hostname to execute command on"
      }
    },
    "optionalParameters": {
      "timeout": {
        "description": "timeout in seconds",
        "default": "120"
        }
    }
  }
}

(GET) / applicabilities

Application can request the list of registered applicabilities with their parameter list.

{
  "HandlerID1": {
    "ExecuteCommand": {
      "on ogit/machineClass == \"linux\" ssh_keyfile ssh_options": {
        "ssh_keyfile": "${ssh_keyfile}",
        "ssh_options": "${ssh_options}"
        },
      "on ogit/machineClass == \"linux\" ssh_keyfile not ssh_options": {
        "ssh_keyfile": "${ssh_keyfile}",
        "ssh_options": "some default options here"
        }
      },
    "ParameterlessExecute": [
      "on ogit/machineClass == \"windows\""
      ]
  }
}

WebSocket Protocol

The websocket is a full duplex TCP connection which allows for the bi-directional communication between the Graph and the Action Handler. Below is the sequence of actions that take place from the engine → graph → the action handler.

URL: wss://core.arago.co/api/action-ws/1.0/
SubProtocol: action-1.0.0

Sample websocket connection request:

var ws = new WebSocket('wss://core.arago.co/api/action-ws/1.0/', ['action-1.0.0', 'token-' + '$token'])
invocation sequence
Figure 2. Invocation Sequence

submitAction

On the successful execution of a KI which requires an action handler, the engine sends a submitAction message to the graph who in turn invokes the action handler and sends the message to it.

Engine → Graph → Action Handler

The sample structure of the message sent by the graph to the action handler is as follows:

{
  "type": "submitAction",
  "id": "the $requestId in App->Graph, the $appId:$requestId in Graph->AH",
  "handler": "handlerId",
  "capability": "capabilityName",
  "timeout": 300000,
  "parameters": {
    "parametername1": "parametervalue1",
    "parametername2": "parametervalue2"
    }
}

All fields are mandatory but content of the "parameters" map is specific to the handler and may contain anything

sendActionResult

Once the action handler is done executing the action it sends back a response to the graph which in turn is sent to the engine by the graph for further processing.

Action Handler → Graph → Engine

The sample structure of the message sent by the action handler to the graph is as follows:

{
  "type": "sendActionResult",
  "id": "the $appId:$requestId in AH->Graph, the $requestId in Graph->App",
  "result": {
    "resultfield1": "resultvalue1",
    "resultfield2": "resultvalue2"
    }
}

Again, the content of the result is specific to the handler and may have any content mapped to it.

ack

This is the acknowledgement sent to confirm to the sender that the message has been received in any of the following cases:

  • Sent back from graph once request has been persisted

  • Sent back from handler once request has been received

  • Sent back from graph once result has been persisted

  • Sent back from engine once result has been received

The structure of an ack message is:

{
  "type": "acknowledged",
  "id": "the $appId:$requestId in AH->Graph, the $requestId in Graph->App",
  "code": 200,
  "message": ""
}

nack

This is the message sent to confirm to the sender that the message has not been received in any of the following cases:

  • Sent back from graph when request could not be persisted

  • Sent back from handler when request can not be handled

  • Sent back from graph when result could not be persisted

  • Sent back from engine when result can not be processed

The structure of an nack message is:

{
  "type": "negativeAcknowledged",
  "id": "the $appId:$requestId in AH->Graph, the $requestId in Graph->App",
  "code": " the error_code ",
  "message": "error description why request was nack'ed"
}