{"componentChunkName":"component---src-templates-default-template-tsx","path":"/ki-syntax/definitions/ki-structure/","result":{"data":{"asciidoc":{"id":"edbec38b-2e73-58db-847f-f84a8441430c","html":"
\n
Table of Contents
\n\n
\n
\n

Introduction

\n
\n
\n

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.

\n
\n
\n
\n
\n

Sections

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

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

\n
\n
\n
\n
\n

Every Knowledge Item is build with these sections:

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Table 1. KI sections
SectionDescription

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

when

Specifies which conditions should exist on the issue to execute the KI

do

Commands to execute in the case of issue binding

\n
\n
\n

ki

\n
\n
    \n
  • \n

    name - KI Name (if KIs are saved to the filesystem, this name should be the same as the filename)

    \n
    • \n
  • \n

    description - KI description

    \n
    • \n
  • \n

    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)

    \n
    • \n
  • \n

    tier - Optional attribute to indicate execution tier the KI belongs to (\"default\", \"policy\" or \"fallback\")

    \n
    • \n
\n
\n
\n

KI Tiers

\n
\n

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

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

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

\n
\n

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.

\n
\n
\n

If the tier is not specified in the KI, it defaults to \"Default\" policy. To assign either of the other two values, you must include the tier attribute with the corresponding value in the KI header.

\n
\n
\n

Imagine you have as ToDos \"OpenTicket\", \"CheckUserExists\" and \"ResetPassword\". Among these three Actions, OpenTicket is designated as the initial step to ensure that subsequent results can be reported to the ticketing system for documentation purposes.\nTo prioritize OpenTicket as the first action, we use the tier feature. OpenTicket is a KI that must always be executed first amongst others, to ensure that subsequent steps can be accurately reported to the ticketing system for documentation purposes.

\n
\n
\n
\n\"Tiers\"\n
\n
\n
\n

The tier must be explicitly stated in the KI header; if left unspecified, the default value for the tier is used.

\n
\n
\n
\n\"Tier\n
\n
\n
\n\n\n\n\n\n
\n\n\nOnly use \"policy\" and \"fallback\" tiers for rare cases where guaranteed prioritized or \"last resort\" execution is absolutely essential.\n
\n
\n
\n
ki Section Example
\n
\n
ki\n  name: \"Tutorial test KI\"\n  version: \"1@Author\"\n  description: \"Tutorial test KI to describe KI Syntax 6.0\"\n  tier: \"default\"
\n
\n
\n
\n
\n
\n
\n

on

\n
\n

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

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

Related Node Matching

\n
\n

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:

\n
\n
\n
Related Node Matching Syntax Template
\n
\n
with <vertexType>@<edgeDirection>[:<edgeType>]\n  <Conditions>\nend
\n
\n
\n
\n

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

\n
\n
\n

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.

\n
\n
\n
Related Node Matching Syntax Example
\n
\n
on\n  ogit/_type == \"ogit/Person\"\n  with ogit/Software/Application@out:ogit/uses\n    ogit/name == \"LunchApp\"\n    ogit/url\n  end
\n
\n
\n
\n

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

\n
\n
\n
    \n
  • \n

    ogit/name attribute has value \"LunchApp\"

    \n
    • \n
  • \n

    attribute ogit/url exists

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

when

\n
\n

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

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

do

\n
\n

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

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

Logical Branching

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

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

\n
\n
\n

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.

\n
\n
\n
\n
\n

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

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

Comments

\n
\n
\n\n\n\n\n\n
\n\n\nSingle 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.\n
\n
\n
\n

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.

\n
\n
\n
\n
# Just a comment\nVarA #This is also a comment
\n
\n
\n
\n
\n\n\n\n\n\n
\n\n\nIf you wish to see how these sections are used you can refer to a full example.\n
\n
\n
\n
","document":{"main":"1.Knowledge Item Structure","title":"1.Knowledge Item Structure","subtitle":""},"fields":{"toc":true,"location":["ki-syntax","definitions","ki-structure"]}},"sidebarYaml":{"id":"6f28bdca-d703-5e79-ae00-b0508f8ee82a","showIndex":true}},"pageContext":{"id":"edbec38b-2e73-58db-847f-f84a8441430c","parent":"ki-syntax"}},"staticQueryHashes":["1010459453","1010459453","2356112386","2356112386","2603905930","2603905930","3026652197","3026652197","3167850324","3167850324","63159454","63159454"]}