Knowledge Item Structure

Overview
Functions
Definitions

Alias
Context
Data types
Data Values
Full example
Knowledge Item Structure
Matching variables and values
Scope
Variables
VarStrings

Automation Issue Lifecycle
Automation Issue Lifecycle - Corner Cases
Hints for KI-Writers
HIRO 6 - Transition Guide for Users having used HIRO 5 before
Transition from KI Syntax 5

Table of Contents

Introduction
Sections
- ki
  - KI Tiers
- on
- on.with
- prepare
- when
- do
  - Logical Branching
Comments

Introduction

Knowledge Items use a YAML-like syntax and are constructed using five major sections. The following document will introduce you to each section and how it is used.

Sections

Mandatory elements for all KI are: ki, name and on. Each KI must additionally have at least prepare and/or the combination when and do.

Valid combinations are:

on, prepare
on, when, do
on, prepare, when, do

Every Knowledge Item is build with these sections:

Table 1. KI sections
Section	Description
`ki`	Meta information about the KI, like `name`, `description` and `version`
`on`	Specifies on which node the knowledge will be applied and which conditions should exist on the node
`prepare`	Commands to execute when KI is bound to a node before the specified conditions are matched
`when`	Specifies which conditions should exist on the issue to execute the KI
`do`	Commands to execute in the case of issue binding

Depending on the type of function your Knowledge Item should perform, you will need different combinations of elements. You can, for example, create a KI that only has the prepare element. It will react to the specified environment and perform certain functionality without relying on a special data situation (when) or actually running external tools or actions (do).

ki

name - KI Name (if KIs are saved to the filesystem, this name should be the same as the filename)
description - KI description
version - (Mandatory Attribute), defines the version of the KI. Proposed form is: 1@author (this should allow to modify the KI in a distributed environment by different people, but still allows easier update later. For example, if the author doesn’t change, then 1@Foo should be updated to 2@Foo, but 2@Foo and 3@Bar would be in conflict, needing manual resolving)
tier - Optional attribute to indicate execution tier the KI belongs to ("default", "policy" or "fallback")

KI Tiers

KIs can be assigned to one of three priority tiers which will affect KI selection priority.

default

the normal KI priority which should be used for almost all normal KIs

policy

the policy level will guarantee execution before KIs of the other tiers

fallback

KIs in this tier will only ever be executed when not default or policy KIs are matching

KI tiers are only applied on a vertex local scope, so a matching "fallback" KI on the current processing vertex will be executed before the issue is routed to a "policy" KI on a connected remote vertex.

Only use "policy" and "fallback" tiers for rare cases where guaranteed prioritized or "last resort" execution is absolutely essential.

ki Section Example

ki
  name: "Tutorial test KI"
  version: "1@Author"
  description: "Tutorial test KI to describe KI Syntax 6.0"
  tier: "default"

on

This section defines where the KI is "bound" meaning a definition of filter elements that specify environment conditions according to the MARS-Model Node data. It could look something like:

on Section Example

on
  NodeType    # exists
  not NodeFoo # not exists
  (NodeType == "Machine")
  OSName =~ "(SLES|Centos)"
  (OSVersion > "7") and (OSVersion < "10") # or OSVersion in 7..10 ?
  with Type@in as ParentScope
    (NodeType == "Resource") or (NodeType == "Software")
    MonitoringEnabled
  end

on.with

This subsection provides an additional restriction to the vertices on which ki will be applied. Namely, the vertex which is matched by the regular conditions in on section must additionally be connected to another vertex of type <vertexType> by an connection of type <edgeType> in direction edgeDirection. The <edgeType> can be omitted which would accept any edge type:

on.with Template

with <vertexType>@<edgeDirection>[:<edgeType>]

where <edgeDirection> can have the following values: in, out, or connected.

It specifies direction of the edge between vertices, can be incoming (in:←), outgoing (out:→) or connected (-). The last one means that condition with is true for any edge direction (in or out), it just checks if edge exists.

on.with SubSection Example

on
  ogit/_type == "ogit/Person"
  with ogit/Software/Application@out:ogit/uses
    ogit/name == "LunchApp"
    ogit/url
  end

That way KI will execute on every vertex of type "ogit/Person" having an outgoing edge of type ogit/uses to a vertex of type ogit/Software/Application which must satisfy the following conditions:

ogit/name attribute has value "LunchApp"
attribute ogit/url exists

prepare

This section is not mandatory. It is used to perform actions when the Knowledge Item is activated regardless of the specified data situation. This can typically be used to initialize temporary variables, contexts or to log additional messages to help debugging or interpreting the processing history. An example can look like this:

prepare Section Example

prepare
  log("adding default aws profile for match")
  AWSProfile = "Company"
  EC2AMI = "ami-12345abcd"
  EC2SecurityGroup = "sg-abc123"
  #EC2SubNet = "subnet-abc123"
  EC2SubNet = "subnet-abc123"
  EC2InstanceType = "m4.2xlarge"

Note however, that pure prepare KIs will only be executed when an issue does KI evaluation on that node. You must not expect the prepare block to be executed on every possible node when deploying the KI. You can however assume that it will be executed before other KIs on the same node are triggered by an actual issue. <<<

when

The instructions defined in do will only be executed when all conditions of when section are matched.

when Section Example

when
  VarA
  VarB["key"] # match on key
  VarC[VarA] == NodeType
  list VarD
  VarF as Test
  MonitoringStatus@any == "true"

do

Once all conditions are matched the Knowledge Item will be applied. The do section defines which actions are performed. It might look like this:

do Section Example

  log.info("bind ki and execute do")
  VarB["new_key"] = 1
  add(NewVar["key"] = "1")
  delete(VarA)
  stdout: ExecuteOutput, exit: LOCAL::Error = execute("path/to/script", timeout: 60)
  if Error then
    log.error("command returned with non-zero exit code")
  else
    log("execute returned ${ExecuteOutput}")
  end

Logical Branching

Designing Knowledge Items with If logic should be avoided. It is much preferred to design atomic Knowledge Items as much as possible.

As a rule of thumb: Deciding between variants of a log message is acceptable. Making decisions about the data condition should be handled in a separate and re-usable Knowledge Item.

You can use the If function to add logical branching to your Knowledge Item.

do
  stdout: ExecuteOutput, exit: LOCAL::Error = execute("path/to/script", timeout: 60)
  if Error then
    log.error("command returned with non-zero exit code")
  else
    log("execute returned ${ExecuteOutput}")
  end

Comments

Single line KI will not work with inline comments. If you wish to use comments in your KI definition you MUST use the long form notation.

You can add comments to you Knowledge Items that explain what certain elements are supposed to do. They simply start with a #. Comments can be added virtually anywhere in the definition.

# Just a comment
VarA #This is also a comment

If you wish to see how these sections are used you can refer to a full example.