{"componentChunkName":"component---src-templates-default-template-tsx","path":"/documentation/api/action-api/","result":{"data":{"asciidoc":{"id":"f3abfbd3-794d-5696-a1cc-c3668d66a756","html":"
\n
Table of Contents
\n\n
\n
\n
\n
\n

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\"\nbetween 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\nAction Handlers on premises and make an outbound connection to the Action API without opening an inbound port.

\n
\n
\n

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\ncommand.

\n
\n
\n

System Architecture

\n
\n
\n
\n\"actionhandler\n
\n
Figure 1. Action API System Architecture
\n
\n
\n
\n
\n

Terminology

\n
\n
\n

Action Handler

\n
\n

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\neither deployed on the HIRO™ SaaS platform itself or on the premises of the customer.

\n
\n
\n
\n

Capability

\n
\n

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

\n
\n
\n
\n

Applicability

\n
\n

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

\n
\n
\n

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

\n
\n
\n
\n
\n
\n

ActionHandler Implementation Requirements

\n
\n
\n

Support for transparent encryption and decryption of sensitive Information

\n
\n

Starting with version 2.3.0 the reference implementation of the HIRO ActionHandler will support asymmetric\ncryptography for secure transportation of sensitive information through the platform. Authors of external\nActionHandlers are strongly encouraged to add support for this functionality as well.

\n
\n
\n

In order to support arbitrary lengths of data, S/MIME has been selected as the data format.

\n
\n
\n

Encrypting capabilities should support the parameter \"EncryptionKey\" that specifies the logical name of the public\nkey to be used for encryption (translates to a locally stored filename atm, will be moved to Graph Key API when released).

\n
\n
\n

The command used to encrypt data in the reference implementation (it is advisable to store VALUE as explicit environment\nvariable before to avoid escaping problems, CERT_FILE should point to the S/MIME Certificate file specified by the\nEncryptionKey parameter):

\n
\n
\n
\n
printf -- \"$VALUE\" | openssl smime -encrypt -aes256 -outform DER $CERT_FILE | base64 -w0
\n
\n
\n
\n

ALL actionhandlers should automatically detect encrypted values contained within their input parameters and try to decrypt\nthese if the corresponding private key is available. The format of the encrypted data in the input parameters is

\n
\n
\n
\n
{{HIROCRYPT/$KEYNAME:$PAYLOAD}}
\n
\n
\n
\n

The command used to decrypt the PAYLOAD data in the reference implementation with KEYFILE name derived from KEYNAME:

\n
\n
\n
\n
echo \"$PAYLOAD\" | base64 -d | openssl smime -decrypt -inform DER -inkey $KEYFILE
\n
\n
\n
\n
\n
\n
\n

Interface / API Definitions

\n
\n
\n

(GET) / capabilities

\n
\n

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

\n
\n
\n

URL: https://core.engine.datagroup.de/api/action/1/capabilities

\n
\n
\n

Response Example

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

(GET) / applicabilities

\n
\n

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

\n
\n
\n

URL: https://core.engine.datagroup.de/api/action/1.0/applicabilities

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

WebSocket Protocol

\n
\n

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.

\n
\n
\n

URL: wss://core.almato.ai/api/action-ws/1.0/
\nSubProtocol: action-1.0.0

\n
\n
\n

Sample websocket connection request:

\n
\n
\n
\n
var ws = new WebSocket('wss://core.almato.ai/api/action-ws/1.0/', ['action-1.0.0', 'token-' + '$token'])
\n
\n
\n
\n
\n\"invocation\n
\n
Figure 2. Invocation Sequence
\n
\n
\n

Payload of messages that go from engine via action api to action handler and back are json encoded strings. All messages must have type argument plus additional arguments specific to that message type.\nOn top of that, all messages except hello also contain id argument. That one represents request id and is used for idempotency. Due to the distributed nature of the system, action api\nimplements sending \"at least once\" strategy, meaning that it might send the same message multiple times but action handler should check if that message id has already been processed or not and act accordingly.

\n
\n
\n

Message types that are in use are:

\n
\n
\n
    \n
  • \n

    hello

    \n
    • \n
  • \n

    submitAction

    \n
    • \n
  • \n

    sendActionResult

    \n
    • \n
  • \n

    acknowledged

    \n
    • \n
  • \n

    negativeAcknowledged

    \n
    • \n
\n
\n
\n
\n

hello

\n
\n

Once connection is successfully established, action handler will receive hello message from action api:

\n
\n
\n
\n
[WsConnection] Received hello message: %{\\\"client_id\\\" => \\\"cloei2yl2h1h4018358ez5g33_cm4ckvw679n5v0193cxogsqwj\\\", \\\"host\\\" => \\\"hiro-graph-actionapi-774f985cc7-f48bl\\\", \\\"server_version\\\" => \\\"0.1.0\\\", \\\"type\\\" => \\\"hello\\\"}\",\"metadata\":{}}
\n
\n
\n
\n

The structure of hello message is:

\n
\n
\n
\n
{\n  \"type\": \"hello\",\n  \"host\": \"action api node that accepted connection\",\n  \"server_version\": \"application version of the action api node\",\n  \"client_id\": \"id of the client in the graph\"\n}
\n
\n
\n
\n

Arguments in this message are of informational nature only.

\n
\n
\n
\n

heartbeat

\n
\n

Action API will send ws ping (not binary) message to connected clients and expects pong message back. If pong message is missing after 3 pings,\naction api will disconnect the client assuming that connection is hanging. Thus, clients should be ready to handle dropped connections and to reconnect.

\n
\n
\n

The same is advised for the clients. They should also send ws ping messages to the action api and reconnect if pong is missing couple of times repeatedly.

\n
\n
\n
\n

submitAction

\n
\n

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.

\n
\n
\n

Engine → Graph → Action Handler

\n
\n
\n

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

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

All fields are mandatory but content of the \"parameters\" map is specific to the handler\nand may contain anything. timeout field is in milliseconds and handler field is not sent to the action handler.

\n
\n
\n

Action API will send the same request each couple of seconds even if action handler acknowledged that request. In such situation, action handler should not execute action again\nbut it still has to acknowledge message.

\n
\n
\n

This behaviour is useful if during action execution action handler is restarted. If it doesn’t have a way to persist ongoing executions, it can rely that action api will resend request that it didn’t receive response for.

\n
\n
\n
\n

sendActionResult

\n
\n

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.

\n
\n
\n

Action Handler → Graph → Engine

\n
\n
\n

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

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

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

\n
\n
\n

It is highly recommended though that result includes action_status which is non-negative number and action_error as nil or string describing why action execution didn’t succeed.\nIf action was executed and is returning result of the execution, action_status should be 0. This status shouldn’t be confused with execution status/code though.\nIt is ok to have http request that returns 500 status code for example, but action_status should still be 0 because response is the result of execution …​ whatever it is.\nThe same situation is for execution of the scripts or commands on a remote machine. action_status is not representation of exit code!

\n
\n
\n

action_status can be used in the KI for debugging or adding some additional logic for the execution or retry.

\n
\n
\n

Action handler should keep sending response to the action api until it gets acknowledged message back.

\n
\n
\n

action_status codes in use

\n
\n

0: \"action executed\"

\n
\n
\n

11: \"Action API didn’t ack request\"\n12: \"Action API didn’t respond\"\n13: \"ActionHandler didn’t respond. Last status in Action API was #{inspect(last_status)}\"\n14: \"ActionHandler responded with execution timeout\"

\n
\n
\n

51: \"AH configuration problem (proxy misconfigured?)\"\n52: \"Request doesn’t match AH config (wrong cert requested?)\"\n53: \"Error preparing request in AH (ah can’t build request with provided args)\"\n54: \"Execution failed/crashed or there was an error with processing response\"

\n
\n
\n

666: \"Unexpected error\"

\n
\n
\n
\n
\n

ack

\n
\n

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

\n
\n
\n
    \n
  • \n

    Sent back from graph once request has been persisted

    \n
    • \n
  • \n

    Sent back from handler once request has been received

    \n
    • \n
  • \n

    Sent back from graph once result has been persisted

    \n
    • \n
  • \n

    Sent back from engine once result has been received

    \n
    • \n
\n
\n
\n

The structure of an ack message is:

\n
\n
\n
\n
{\n  \"type\": \"acknowledged\",\n  \"id\": \"the $appId:$requestId in AH->Graph, the $requestId in Graph->App\"\n}
\n
\n
\n
\n
\n

nack

\n
\n

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

\n
\n
\n
    \n
  • \n

    Sent back from graph when request could not be persisted

    \n
    • \n
  • \n

    Sent back from handler when request can not be handled

    \n
    • \n
  • \n

    Sent back from graph when result could not be persisted

    \n
    • \n
  • \n

    Sent back from engine when result can not be processed

    \n
    • \n
\n
\n
\n

The structure of an nack message is:

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

code 404 should be returned from the action handler if it doesn’t support requested capability

\n
\n
\n
\n
","document":{"main":"HIRO Graph Action API","title":"HIRO Graph Action API","subtitle":""},"fields":{"toc":true,"location":["documentation","api","action-api"]}},"sidebarYaml":{"id":"6d066bdd-c982-5a69-b909-a31e6fc044e0","showIndex":null}},"pageContext":{"id":"f3abfbd3-794d-5696-a1cc-c3668d66a756","parent":"documentation"}},"staticQueryHashes":["1010459453","1010459453","2356112386","2356112386","2603905930","2603905930","3026652197","3026652197","3167850324","3167850324","63159454","63159454"]}