{"componentChunkName":"component---src-templates-default-template-tsx","path":"/tutorials/tutorial-first-incident-connector/","result":{"data":{"asciidoc":{"id":"33bb1e14-ed88-547e-b660-15593e26e189","html":"
\n

First incident connector

\n
\n
\n

The Domain Object Api expects messages in sdf format. The sdf format is defined in views, e.g. the sdf for an incident is defined.

\n
\n
\n

Creating the model

\n
\n

Before we can start sending incidents to HIRO we need to have a model or representation of the environment which we want to automate in the system.\nThe smallest possible model is a single Node. Such a default node can be created by the Domain Object Api with

\n
\n
\n
\n
curl -kH 'Content-type:application/json' -X PUT 'https://doapi.almato.ai/views/default/objects/defaultMachineId' -d '{\"$type\":\"configMachine\",\"name\":\"defaultMachine\",\"systemType\":\"Virtual\"}'
\n
\n
\n
\n

The SDF message in the call to define the default node looks like:

\n
\n
\n
\n
{\n  \"$type\": \"configMachine\",\n  \"name\": \"defaultMachine\",\n  \"systemType\":\"Virtual\"\n}
\n
\n
\n
\n

In the following calls the defaultMachineId can be used to define the starting point in the model for newly created Automation Issues. An Automation Issue represent any kind of automation task. In the following we will take incident as an example.

\n
\n
\n
\n

Creating an Incident

\n
\n

To create an Automation Issue which represents an incident the following call can be made to the Domain Object Api:

\n
\n
\n
\n
curl -kH 'Content-type:application/json' -X PUT 'https://doapi.almato.ai/views/default/objects/inc-0001' -d' {\"$type\":\"incident\",\"subject\":\"My first incident\",\"originNode\":\"defaultMachineId\",\"summary\":\"This is the first incident created by me\",\"priority\":\"important\",\"description\":\"The incident was created for testing.\",\"urgency\":\"high\",\"sourceStatus\":\"open\"}'
\n
\n
\n
\n

The SDF message in this call is

\n
\n
\n
\n
{\n  \"$type\": \"incident\",\n  \"subject\": \"My first incident\",\n  \"originNode\": \"defaultMachineId\",\n  \"summary\": \"This is the first incident created by me\",\n  \"priority\": \"important\",\n  \"description\": \"The incident was created for testing.\",\n  \"urgency\": \"high\",\n  \"sourceStatus\": \"open\"\n}
\n
\n
\n
\n

In HIRO the following AutomationIssue will be created:

\n
\n
\n
\n
{\n  \"/ProcessIssue\": \"process me\",\n  \"/actual_type\": \"IncidentType\",\n  \"/description\": \"The incident was created for testing.\",\n  \"/priority\": \"important\",\n  \"/sourceStatus\": \"open\",\n  \"/summary\": \"This is the first incident created by me\",\n  \"/urgency\": \"high\",\n  \"ogit/Automation/originNode\": \"defaultMachineId\",\n  \"ogit/_graphtype\": \"vertex\",\n  \"ogit/_id\": \"cjqzbn759dxq27f58egrs3ped\",\n  \"ogit/_type\": \"ogit/Automation/AutomationIssue\",\n  \"ogit/_xid\": \"prefix:inc-0001\",\n  \"ogit/status\": \"PROCESSING\",\n  \"ogit/subject\": \"My first incident\"\n}
\n
\n
\n
\n

The issue will be processed by HIRO. Different knowledge Items kis will be applied to solve the task at hand.

\n
\n
\n

If the incident sdf does not contain required attributes, either new attributes can be requested on OGIT, or free attribute (starting with /) can be sent to the Domain Object Api.

\n
\n
\n
\n
{\n  \"$type\": \"incident\",\n  \"subject\": \"My first incident\",\n  \"originNode\": \"defaultMachineId\",\n  \"summary\": \"This is the first incident created by me\",\n  \"description\": \"The incident was created for testing.\",\n  \"/test\": \"this is a free test variable\"\n}
\n
\n
\n
\n
\n

Check message was successful

\n
\n

The Domain Object Api has non-blocking calls. So the execution of a call to create or update an incident (and any other type of sdf) will return a message with a transaction link.

\n
\n
\n
\n
{\n  \"link\": \"/views/default/transactions/0c6fc0cd-d6c9-4ad0-a965-859e6a3771bd\",\n  \"object\": \"/views/default/objects/inc-0001\",\n  \"status\": \"waiting\",\n  \"requestedAt\": 1616745367187,\n  \"updatedAt\": 1616745367187,\n  \"startedAt\": -1,\n  \"errors\": []\n}
\n
\n
\n
\n

The transactions can be checked by the link or by

\n
\n
\n
\n
curl https://doapi.almato.ai/views/default/transactions
\n
\n
\n
\n
\n
  {\n    \"link\": \"/views/default/transactions/0c6fc0cd-d6c9-4ad0-a965-859e6a3771bd\",\n    \"object\": \"/views/default/objects/inc-0001\",\n    \"status\": \"done-success\",\n    \"requestedAt\": 1616745367187,\n    \"updatedAt\": 1616745369450,\n    \"startedAt\": 1616745369335,\n    \"errors\": []\n  }
\n
\n
\n
\n

If the transactions was done successfully the status of the transaction will show done-success. More details can be found in\ntransactions documentation.

\n
\n
\n

It is also possible to subscribe to the transactions via websocket with transaction.done-success and transaction.done-failure respectively.

\n
\n
\n
\n

Getting updates

\n
\n

Once HIRO starts working on the Automation Issue, every step will be documented. Every step will be exposed as an update message by the Domain Object Api.

\n
\n
\n

To check the updates, following call can be done with offset or iterator as a parameter.

\n
\n
\n
\n
curl https://doapi.almato.ai/views/default/updates?offset=0
\n
\n
\n
\n

The updates have the following format:

\n
\n
\n
\n
[\n  {\n    \"link\": \"/views/default/updates/0\",\n    \"offset\": 0,\n    \"object\": {\n      \"summary\": \"The summary has been updated by HIRO\",\n      \"hiroStatus\": \"PROCESSING\",\n      \"$delta\": [\n        \"summary\"\n      ],\n      \"comments\": {\n        \"inc-0001-COMMENT\": {\n          \"$delta\": [],\n          \"comments\": []\n        }\n      },\n      \"$type\": \"incident\",\n      \"$id\": \"inc-0001\"\n    }\n  }\n]
\n
\n
\n
\n

In $id the id of the incident for which the update is sent is shown.\nIn $delta the fields are shown which have changed by HIRO.\nThe comments section shows the steps done by HIRO.

\n
\n
\n

It is also possible to subscribe to the updates via websocket with update.received.

\n
\n
\n
\n

Interactive communicating with HIRO

\n
\n

Comment or work notes can be sent to the Domain Object API, on creation or while the incident is being processed by HIRO. If an incident is created like described in Creating an Incident an additional comment can be added. For example a comment can be sent to stop processing:

\n
\n
\n
\n
curl -kH 'Content-type:application/json' -X PUT 'https://doapi.almato.ai/views/default/objects/inc-0001' -d '{ \"$type\": \"incident\", \"comments\": { \"inc-0001-COMMENT\": { \"comments\": [{ \"timestamp\": 1584632631000, \"value\": \"[HIRO] Please eject\" }] } } }'
\n
\n
\n
\n

The SDF message in this call is:

\n
\n
\n
\n
{\n  \"$type\": \"incident\",\n  \"comments\": {\n    \"inc-0001-COMMENT\": {\n      \"comments\": [\n        {\n          \"timestamp\": 1584632631000,\n          \"value\": \"[HIRO] Please eject\"\n        }\n      ]\n    }\n  }\n}
\n
\n
\n
\n

Now this is added to the /comments attribute in the Automation Issue. Additionally, it is stored in a timeseries vertex with the name UserComment.\nA ki can react on this comment. HIRO will eject the Automation Issue, if the following ki is deployed:

\n
\n
\n
\n
ki\n  title: \"Eject issue on request\"\n  description: \"Eject issue on request\"\non\n  ogit/_id\nwhen\n  comments =~ \"[HIRO].*eject\"\n  ProcessIssue\ndo\n  eject_issue(\"Issue has been ejected on request\")
\n
\n
\n
\n

This will result in a changed processing status of the Automation Issue. This is reflected in an update exposed on the Domain Object Api’s update endpoint:

\n
\n
\n
\n
 {\n    \"link\": \"/views/default/updates/1\",\n    \"offset\": 1,\n    \"object\": {\n      \"summary\": \"The summary has been updated by HIRO\",\n      \"hiroStatus\": \"TERMINATED\",\n      \"$delta\": [\n        \"hiroStatus\"\n      ],\n\n      \"$type\": \"incident\",\n      \"$id\": \"inc-0001\"\n    }\n  }
\n
\n
\n
\n

Depending on the kis available in HIRO different reactions can follow a comment in the incident.

\n
\n
\n
\n
","document":{"main":"First incident connector","title":"First incident connector","subtitle":""},"fields":{"toc":false,"location":["tutorials","tutorial-first-incident-connector"]}},"sidebarYaml":{"id":"0acf6fc1-95eb-5854-8f81-d5561b07a582","showIndex":null}},"pageContext":{"id":"33bb1e14-ed88-547e-b660-15593e26e189","parent":"tutorials"}},"staticQueryHashes":["1010459453","1010459453","2356112386","2356112386","2603905930","2603905930","3026652197","3026652197","3167850324","3167850324","63159454","63159454"]}