Our guides are catered for maximum efficiency to the role a user has while automating with Bardioc™. Please select from the below if you’re a Subject Matter Expert (SME) or an AI Expert (AIE).
\nBardioc Desktop / Bardioc UI can be used on most modern browsers, but works best on the two most recent versions of:
\nTerm | \nMeaning | \n
ACL | \nAccess Control List | \n
API | \nApplication Programming Interface | \n
ASN | \nAutonomous System Number | \n
AWS | \nAmazon Web Services | \n
BGP | \nBorder Gateway Protocol | \n
CIDR | \nClassless Internet Domain Routing | \n
DNS | \nDomain Name System | \n
HTTPS | \nHypertext Transfer Protocol over SSL | \n
IP | \nInternet Protocol | \n
ITSM | \nInformation Technology Service Management | \n
KAT | \nKnowledge Acquisition Tool | \n
KE | \nKnowledge Expert | \n
KI | \nKnowledge Item | \n
KIM | \nKnowledge Item Manager | \n
LB | \nLoad Balancer | \n
OGIT | \nOpen Graph IT | \n
SaaS | \nSoftware as a Service | \n
SME | \nSubject Matter Expert | \n
SSL | \nSecure Sockets Layer | \n
RL | \nReinforcement Learning | \n
TLS | \nTransport Layer Security | \n
VPC | \nVirtual Private Cloud | \n
VPN | \nVirtual Private Network | \n
Attribute-based access control. Attribute-based access control defines an access control paradigm whereby access rights are granted to users through the use of policies which combine attributes together. The policies can use any type of attributes (user attributes, resource attributes, object, environment attributes etc.). Source: Wikipedia
\n\"Access Control List\" (ACL). An access control list (ACL), with respect to a computer file system, is a list of permissions attached to an object. An ACL specifies which users or system processes are granted access to objects, as well as what operations are allowed on given objects. Source: Wikipedia
\nAction handlers are external service points the engine utilizes to get\nthings done it can’t do it itself. Hence the engine (usually being the\n\"server\") now becomes the client and sends out request to a suitable\nAction Handler.
\nApache Cassandra is an open source distributed database management\nsystem designed to handle large amounts of data across many commodity\nservers, providing high availability with no single point of failure.\nCassandra offers robust support for clusters spanning multiple\ndatacenters, with asynchronous masterless replication allowing low\nlatency operations for all clients. Source:\nWikipedia
\nAn 'Application Node' within the MARS Model is describing the end user\nperspective towards IT. Typically an Application consists of a number of\nresources / Resource Nodes.
\nSetting up an basic environment, e. g. using a boot loader.
\nsee Apache Cassandra.
\n\"Configuration Item\". Configuration information within the MARS Model. See also CMDB.
\n\"Command Line Interface\". Command line interface that enables the direct\ninput of commands.
\n\"Configuration Management Database\". Contains the information supplied by\nthe customer about construction and composition of the defined IT\nenvironment as per the MARS model.
\nDatabase Management System
\nModel showing dependencies between different Configuration\nItems/Services, aka MARS-Model.
\nsee MARS Model
\nAmazon Elastic Compute Cloud (EC2) is a central part of Amazon.com’s\ncloud computing platform, Amazon Web Services (AWS). EC2 allows users to\nrent virtual computers on which to run their own computer applications.\nSource:\nWikipedia
\nAn event is an action or occurrence detected by the program that may be\nhandled by the program. Source:\nWikipedia
\n\"A graph is a representation of a set of objects where some pairs of\nobjects are connect by links.\" Source:\nWikipedia
\nSee Bardioc Graph.
\nHigh Availability
\nConcept that provides systems available 99% (or more) of the time.
\nBardioc Command Line Interface Tools. A set of tools to simplify the most common graph operations for Knowledge Items, MARS Nodes and Issues.
\nIssue processing and logic core
\nBardioc Graph is a distributed graph storage holding data defined in OGIT. It\nis also the underlying storage engine for the Bardioc.
\nIdentity and Access Management.
\nThe information situation is part of an Issue and consists of all\ninformation available for decision taking. It is extend and/or updated\nby Knowledge Items until the conclusion of the Issue task. The choice of\nKnowledge Item that will be applied next to an Issue is based on the\ninformation situation.
\nAn Issue is a task which, in a formalized manner, is handed over to the\nengine via an interface. The engine then attempts to resolve Issues with the\nhelp of Knowledge Items. Technically speaking, an Issue is a\ndata container, collecting information from various sources.
The \"Issue Condition\" (IC) is the state the data is in. The Issue\nCondition defines which state triggers the Knowledge Item(s) associated\nwith this particular IC.
\n\"Java Database Connectivity\", an API which defines how a Java client can\naccess a database
\n\"JavaScript Object Notation\" (JSON) is a lightweight data-interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate. It is based on a subset of the JavaScript Programming Language, Standard ECMA-262 3rd Edition - December 1999.
\nJava(tm) Development Kit
\nThe \"Java Naming and Directory Interface\" (JNDI) is a Java API for a directory service that allows Java software clients to discover and look up data and objects via a name.
\nJava(tm) Runtime Environment
\n\"Kafka is a distributed, partitioned, replicated commit log service. It\nprovides the functionality of a messaging system, but with a unique\ndesign.\" from Kafka\nintroduction
\nThe KI Editor is the central maintenance tool for Knowledge Items.
\nsee Knowledge Item
\nA \"Knowledge Item\" (KI) is a piece of knowledge data which is used to\nresolve Issues. A Knowledge Item determines the necessity of its\nexecution by checking the state of presented information. In case the\ninformation points to a problem that can be solved by the Knowledge Item\nit further gathers information to determine how to proceed or executes\ncommands to directly address the presented Issue.
\nThe Knowledge Pool is the sum of all Knowledge Items used by the engine.
\nAn Machine Node within the MARS Model is usually describing the\nphysical infrastructure component (hardware), that is capable of\nrunning one to many software components.
A machine learning service is a service that uses\nstatistical techniques to give computer systems the ability to \"learn\"\n(e.g., progressively improve performance on a specific task) from data, without being explicitly programmed.
\nThe MARS Model describes and categorizes IT objects within a system and\nrepresents the relationships between them.
\nA node in general is an object with a Graph structure. The engine builds a\ngraph structure out of the MARS Model description, so any object\ncontained in a MARS model is represented by a node in the Autopilot\ndatabase.
\nWithin the Bardioc Graph database there are four basic types of nodes:\nMachine, Software, Resource and Application.
\nOAuth is an open standard to authorization. OAuth provides client\napplications a secure delegated access to server resources on behalf\nof a resource owner. Source:\nWikipedia
The \"Open Graph of IT\" aims to build a semantic representation of all IT\nand its interaction with business processes and people, also known as\nthe \"Facebook of IT\". The OGIT ontology project targets to provide a\ncommon language by defining an ontology for the Graph of IT. Find more\ninformation at OGIT Repository.
\n\"Role-based-access-control\" (RBAC) is a policy neutral access control mechanism defined around roles and privileges. The components of RBAC such as role-permissions, user-role and role-role relationships make it simple to perform user assignments. Source: Wikipedia
\n\"Relational Database Management System\", a database management system\nbased on the relational model
\nRegular Expression
\n\"Representational State Transfer\" (REST) is a software architecture style\nconsisting of guidelines and best practices for creating scalable web\nservices. REST is a coordinated set of constraints applied to the design\nof components in a distributed hypermedia system that can lead to a more\nperformant and maintainable architecture. Source:\nWikipedia
\nResource (Node)
\n\"RPM Package Manager\" (RPM) (originally Red Hat Package Manager; now a\nrecursive initialism) is a package management system. Source:\nWikipedia
\nAlmato \"Standard Data Format\". A proprietary but open data format developed by\nAlmato for exchange between ITSM systems and Bardioc Connect.
\nSoftware (Node)
\nSingle Sign-On
\nA time series is a sequence of data points, measured typically at\nsuccessive points in time spaced at uniform time intervals.
\nTime To Live
\nA token can either be a session identifier or a substitute for\nauthorization credentials, depending on the context of the application.\nIt serves to identify users or applications. For more information please\nrefer to\nTokenization or\nSession ID
\nThe \"Well-Known Addresses\" (WKA) scheme is a mechanism that allows cluster members\nto discover and join a cluster using unicast instead of multicast.\nWKA is enabled by specifying a small subset of cluster nodes (referred to\nas WKA nodes) that are able to start a cluster. The WKA node starts the\ncluster and the other nodes join it through this WKA node.\nIf the WKA node is down, the cluster breaks, and the nodes will not be able\nto communicate with each other.
\nThe system should have at least two well-known address (WKA) members in order\nto work correctly and to recover if a single WKA member fails.
\nThis typically refers to the WSO2IS component.
\nThe WSO2 Identity Server is an open source identity & entitlement\nmanagement server having support for Information Cards, OpenID and\nXACML. Source: Wikipedia.
\n\"Extensible Markup Language\" (XML) is a markup language that defines a\nset of rules for encoding documents in a format that is both\nhuman-readable and machine-readable. It is defined in the XML 1.0\nSpecification produced by the W3C, and several other related\nspecifications, all free open standards.\"\" Source:\nWikipedia
\nXML name space
\n\"XML Schema Definition\". A schema is a collection of metadata, that\ndescribes and validates data in an XML environment.
\n\"YAML is a human-readable data serialization format that takes concepts\nfrom programming languages such as C, Perl, and Python, and ideas from\nXML and the data format of electronic mail\" Source:\nWikipedia
\nThe Apache Zookeeper Tool is used in HA setups to maintain configuration\ninformation for distributed services.
\nFixed issue where users got logged out before the expected time of 60 minutes of inactivity.
\nUsers with access to Bardioc instances of multiple organisations can now switch between organisations in Bardioc Desktop.
\nFixed Logout going to 404
\nFixed issue where a user’s role is incorrectly displayed
\nFixed issue where apps failed to load when no Instance was selected
\nUpdated auth API version
\nUpdate website links to use almato.com
\nInternal code optimization
\nChanged statistics panel in Bardioc Desktop’s dashboard to calculate data for the last 24 hours instead of since midnight
\nFixed bug in how automation rate was calculated
\nAllows you to browse and navigate all your accessible data
\nNew graph view mode lets you see all incoming and outgoing edges at a glance
\nNew filter and search options available
\nUse panels to create a customized view of your data. Panels can be saved for quick access.
\nAvailable to all customers and users (SME and AIE)
\nBugfix: Fixed problem with Bad Gateway
\nNEW: Added capability to inject both issue and node in one csv file
\nNEW: Updated Connector URL. Simply replace your existing url with the new one. More information can be found\nhttps://developer.bardioc.almato.com/7.0/documentation/integration/CSV/connector/
\nImproved tagging of Knowledge Items\n* you can now view tags in the Task Inspector\n* add tags in the Knowledge Aquisition Tool (Knowledge Item linking and editing) and Task Inspector\n* use a color palette to increase the number of tag colors\n* add tooltips for tags
\nNEW: Introducing tag tooltips for Knowledge Acquisition Tool, Knowledge Item Manger and Task Inspector
\nNEW: Increased number of available colors for tags by intrudicing a color picker
\nBugfix: KI comments update when changing steps
\nBugfix: KI changes were not saved under certain conditions
\nNEW: Ability to add Tags
\nNEW: Ability to view tags
\nVarious bug fixes (fixed duplicate variable listing and wrong key deletion)
\nImproved the duration value to now shows milliseconds, seconds, minutes, hours, and days
\nReduced time to load Task Timeline events
\nExternal changes are highlighted in light grey in Task Content Display (Changes to the issue not performed by the engine)
\nKI version in Knowledge Item panel is now available. Allows you to tell which version of the KI was executed at this given time
\nRedesign with enhanced functionality
\nKI executions grouped by node
\nImproved duration highlighting
\nAdded visual representation of variable changes
\nKI alternatives displayed and accessible within Task Inspector
\nAIE Dashboard automation rate widget allows to query by day week and month
\nAdd Activity Log Events
\nUpdate Variable Highlight Colours
\nUpdate Internal Dependencies
\nRemove IE11 Support
\nImprove when Knowledge Item Saving Indicator is Shown
\nEnable Fork for Undeployed Knowledge Items
\nFix Bug with SME Handover
\nFix Undefined Knowledge Item Pool Bug
\nFix Todo Variables being shown as Plain Variables
\nFix Todo Checkbox Occasionally being hidden When Creating a New Variable
\nAdd Activity Log Events
\nUpdate Internal Dependencies
\nUpdate Variable Highlight Colours
\nEnsure App State is Persisted on Page Refresh
\nFix Bug where Lists with Keys are Presented as a Single String
\nCollapse Arrow is Visible by Default
\nReduce Indentation for Objects in Task View
\nMake Objects Collapsed by Default if Over 5 Lines in Task View
\nFix Bug where Variable Tooltips were Broken
\nAdd Activity Log Events
\nUpdate Internal Dependencies
\nFix Bug Where Search is not Working for Multiple Words
\nAdd Activity Log Events
\nUpdate Variable Highlight Colours
\nAdd Activity Log Events
\nRelease Bardioc Dashboard as a Self-contained Bardioc Desktop App
\nRemove Bardioc Dashboard as a Dependency of Bardioc Desktop
\nFix Empty Task History
\nRemove IE11 Support
\nFix Styling Bug
\nFix Bug where Task History Differs for The Task Node
\nShow JSON Values as Structures
\nShow Task Structure in Pretty View (with Raw View Toggle)
\nHide Task OGIT Values by Default (Show with Toggle)
\nAdd Show/Hide INFO Values Toggle
\nShow Search Results in Best Match Order
\nRemove IE11 Support
\nRemove IE11 Support
\nFormat List Variables in Chat View
\nUnify App Spacing
\nAllow Links to Open in a New Tab
\nFix Step Name being Updated when User Edits Step Field
\nFix Typo
\nUpdate Internal Dependencies
\nUnify App Spacing
\nAllow Links to Open in a New Tab
\nUnify App Spacing
\nAllow Links to Open in a New Tab
\nAllow to Filter Task by Time
\nImplement Resize / Rearrange Functionality (beta)
\nUpdate Event Stream to Scope-Specific Stream
\nUnify App Spacing
\nAllow Links to Open in a New Tab
\nAdd Required / Optional Fields Parameter
\nImprove JSON Structure Validation
\nFix bug with Expired Token causing Desktop to Freeze
\nFix Bug with Search where an Unexpected Character can Cause a Crash
\nRemove IE 11 Support
\nUpdate Internal Dependencies
\nUpdate Event Stream to Scope-Specific Stream
\nFix Bug that causes Task Inspector to crash when loading Task History
\nFix Bug with Deployment Filter not working for Deployed KIs
\nAdd Bardioc Task Approval for Approval Action Handler
\nDont hide Scrollbar on History Timeline
\nUpdate Knowledge Item view to match Knowledge Item Manager and Knowledge Acquisition Tool
\nOpen Knowledge Item in Knowledge Item Manager Button
\nUpdate Internal Dependencies
\nAdd Desktop Notification UI
\nCombine Role and Workspace Switch
\nUI Fixes for IE11
\nSearch UX Improvement
\nMake App List Scrollable
\nUpdate Internal Dependencies
\nAdd Highlighting of Variables in Knowledge Item Matching Dialog
\nFix Invalid Date In Chat Messages
\nFix Issue where Editing Steps Chat Causes a Blank Screen
\nUpdate Dashboard
\nImprove Bardioc Tasks Progress Bar
\nPass Instances Settings to Applications
\nImprove Task Search
\nImprove Knowledge Item Matching (Search)
\nUpdate Internal Dependencies
\nUnify Dropdown Filters Across All Desktop Applications
\nFix Bug Where Text Is Accidentally Cropped
\nAllow Closing The Task List Dialogue
\nUpdate Internal Dependencies
\nUnify Dropdown Filters Across All Desktop Applications
\nFix Bug Where Popover With Long Content Is Cut
\nFix Jumping Tables On Load More
\nFix Bug Where Code Editor Can Become Empty In Safari
\nUpdate Internal Dependencies
\nUnify Dropdown Filters Across All Desktop Applications
\nFix Bug Where Table Row Blinks Under Certain Circumstances
\nFix Jumping Tables On Load More
\nUpdate Internal Dependencies
\nUnify Dropdown Filters Across All Desktop Applications
\nFix Bug Where Table Row Blinks Under Certain Circumstances
\nFix Bug Where Comments Can’t Be Left For Chat Messages
\nAllow Closing The Task List Dialogue
\nFix Undefined Value in Mixed Lists or Dictionaries
\nFix Accidental Removal of Whitespace from Task
\nGeneric UI and Performance Improvements
\nUpdate Dry Start Modal
\nRemove the Slide-Out List
\nAdd Direct Link to Graph Explorer
\nGeneric UI and Performance Improvements
\nAdd Improved Code Editor Menu
\nAdd Syntax Highlighting in Code Editor
\nAdd Word-Wrap Toggle
\nGeneric UI and Performance Improvements
\nImprove Bardioc Tasks Progress Bar
\nFix Issue where Search breaks on certain characters
\nFix loading issue when filters are updated mid process
\nGeneric UI and Performance Improvements
\nUpdate Dry Start Modal
\nImprove Bardioc Tasks Progress Bar
\nAdd Word-Wrap Toggle
\nMake Full Screen CTA Sticky
\nFix Comments not being visible under certain circumstances
\nFix Variable Validation Pop-Up
\nAllow Comments to be Un-Resolved
\nFix Issue with KI Searching
\nImprove Syntax Highlighting for Function Names
\nFixed issue where Task list is obscured by header
\nFixed issue where mixed list dont show keys
\nFixed issue where the wrong brackets where being used
\nFixed issue where only one value per key was being shown
\nFixed issue where undefined was being shown for deleted lists
\nFixed issue where Task Inspector crashes and goes white, when clicking on an Event
\nFixed bug where lists where showing as undefined
\nNew tasks shown in dry start list
\nLive updates of KI executions fixed
\nFixed bug where Task Inspector was showing removed variables
\nImproved error handling for Nodes that can not be displayed
\nImprove KI Validation message
\nImprove Deploy Controls
\nImprove Search
\nVariable validation fix
\nShow all comments automatically, when removing comment source
\nChat Improvements
\nStability improvements
\nKI Matching improvements
\nAdd Step Button under selected step
\nMove Code View Menu
\nReview Flow: Highlight Mentioned Reviewer
\nReview Flow: Re-ping Reviewers
\nReview Flow: Add Reviewer Button
\nReview Flow: User Mentioning
\nImprove KI Detach
\nFixed bug where function names were highlighted
\nBardioc {releasever} provides new functionality and some bug fixes.
\nSimplified access to Bardioc Instances and user-role management.
\nAccounts are created and managed in a single place by their Organization Admin.
\nThis enables Organization Admins to:
\nAdd or remove users' access to an Instances and Roles,
\nActivate or deactivate users' accounts,
\nInvite new users as well as request password resets.
\nSingle accounts can have access across multiple Instances.
\nAccounts can be managed online with users being able to update their own profile and password.
\nAccess to Bardioc Instances is controlled by the Organization Admin.
\nUsers can be added or removed from an Instances via their Team membership.
\nUsers can be provided Subject Matter Expert and/or AI Experts access per Instance.
\nAction Handler have been removed from the Engine / Engine configuration. The new Action Handlers flow is Engine → Graph → Action Handler
Simplified setup and configuration
\nAction Handlers can be deployed on user’s infrastructure without touching inbound ports on their firewall (which is usually avoided due to security reasons)
\nUsers can implement their own Action Handlers following defined ActionAPI protocol
\nSwitching between different instances
\nUsers can select different instances within Bardioc Desktop
\nEase of use with visibility of all instances in one place
\nReview Feature for Subject Matter Experts & AI Experts
\nAllows users to share teaching sessions with their peer group for review
\nOffers feedback opportunity to both Subject Matter Experts and AI Experts on any individual knowledge that was created
\nProgress on reviewed teaching sessions can be tracked on dashboard
\nPagination is replaced by Lazy-List loading
\nPagination is replaced by Lazy-List loading
\nPagination is replaced by Lazy-List loading
\nPagination is replaced by Lazy-List loading
\nEasy navigation for users between different applications based on the scope of their role
\nFollowing applications are available for Subject Matter Experts & AI Experts:
\nSubject Matter Experts:
\nBardioc Dashboard (Subject Matter Experts)
\nBardioc Task List
\nBardioc Knowledge Acquisition Tool
\nAI Experts
\nBardioc Dashboard (AI Experts)
\nBardioc Task List
\nBardioc Knowledge Acquisition Tool
\nBardioc Knowledge Manager
\nBardioc Task Inspector
\nThis guide contains all the essential information for Admins to operate Bardioc™ effectively for best results.
\nBardioc™ is an automation tool based on artificial intelligence, created by Almato. It can be used to automate both IT and business processes, enabling companies to utilise time and resources effectively.
\nBardioc™ is always working in the background, whether that be carrying out tasks, or learning new ones. This can be seen in the two modes Bardioc™ works in:
\nBardioc™ solves tasks automatically by applying pre-existing knowledge.
\nBardioc™ gets taught new knowledge to automate new tasks in an agile manner.
\n![\"map](\"/7.0/images/MotW_simple.png\")
\nPrimarily, Bardioc™ needs to understand the environment that it will automate in, including which tasks can occur there. These can both be extended as the scope grows, but to start off one should select an end to end process to automate, and define which tasks can occur there and their triggers.
\nTriggers will be defined for each problem type, and an Automation Task will be created in Bardioc™ every time a trigger is detected. In the Automatic Execution Mode, Bardioc™ tries to solve each task by applying existing knowledge that it will have been taught previously.
\nIf the knowledge present is not sufficient for a specific task, Bardioc™ will request to be taught new knowledge in the Agile Automation Mode, so that it can solve the task automatically the next time a similar trigger occurs.
\nAutomating with Bardioc™ entails indirectly collaborating with various team members that will each use Bardioc™ differently. For this purpose, Almato has created some User Roles to better separate responsibilities, processes for hand-over, and allow for the user interface and training content to be better catered to each role.
\nSolution Design is carried out by a Business Analyst who is familiar with the business process, and understands how Bardioc™ works. They design how all components will work together and what is to be developed.
\nA Bardioc™ Developer is responsible for creating and configuring the Action Handlers and Connectors planned in the Solution Design phase. They are familiar with the source and target systems, and the available Bardioc™ APIs.
\nExperts who will teach Bardioc how to automate processes they are knowledgeable on through a chat conversation where they answer some questions regarding said processes and tasks within them.
\nThis role will be given to users who understand how Bardioc works, and can edit Bardioc’s automatically generated code to ensure it has translated content from an SME’s chat conversation correctly into KIs.
\nThis role will be given to users who understand how Bardioc works, permissions required for each user, and how to configure this using Bardioc™ User Interface.
\nBardioc™ is taught new knowledge during task automation by a combination of two different types of users - the Subject Matter Experts (SMEs) and the Knowledge Experts (KEs). For this to happen smoothly each user role has different permissions and ways of interacting with Bardioc™. SME’s should be able to see the Tasks that are relevant to them and their team; whereas AI Experts will need to see completed Teaching Sessions that are handed over by SMEs after knowledge transfer.
\nUser Self-registration
\nIn order to use Bardioc 7, a user must first register at id.almato.com. on the registration page. Here the user needs to use an email address from the organization which is granting them access to the Bardioc instance. For example, Sarah at almato.com wants to register at id.almato.com.
\n![\"RegistrationPage\"](\"/7.0/images/admin-ug/RegistrationPage.png\")
\nTo create a user, Sarah has filled in the fields found on the right-hand side of the screen. First Name, Last Name, and Email Address are the minimum requirements to proceed. She can opt in to receiving emails from Almato regarding Bardioc activity, by ticking the checkbox below the fields. When these are filled in, Sarah presses the “I AGREE, Register Now” button, and waits for her registration email.
\n![\"UserRegistrationSection\"](\"/7.0/images/admin-ug/UserRegistrationSection.png\")
\nA registration email should arrive shortly after clicking the Register Now button. If you can’t see this in your inbox, please make sure to also check the junk folder, as this may sometimes be incorrectly categorized as spam. It’s important to do this promptly as the email will contain a link that expires 24 hours after it’s received. The link is found on the bottom right with a “FINISH REGISTRATION” button and this will take Sarah to the screen where she can create a password for her new Almato ID user account and add a picture to customize.
\n![\"RegistrationEmail\"](\"/7.0/images/admin-ug/RegistrationEmail.png\")
\nHow access is granted for a Bardioc 7 instance
\nEach Bardioc 7 instance has its own so called “haas-id”. In the example below, Sarah is a member of the teams “knowledge experts” and “subject matter experts” for the instance haas28806. She can access this instance by logging on to desktop.bardioc.almato.com. Bardioc 7 instances are created by Almato, user management can be done by any organisation administrator (Almato will assign one client administrator to begin with).
\n![\"sarahtrue\"](\"/7.0/images/admin-ug/sarahtrue.png\")
\n![\"desktopsarah\"](\"/7.0/images/admin-ug/desktopsarah.png\")
\nAssigning members to teams
\nTo assign a member of your organisation to a team, simply navigate to the teams tab and start searching for the team member. Keep in mind that only administrators have the privilege to do this. You can find out who is administrator by looking at the member list of the team admin. The administrator can add additional administrators.
\n![\"teams\"](\"/7.0/images/admin-ug/teams.png\")
\nIn the example below, we are adding Daniel to the knowledge_experts team.
\n![\"adddan\"](\"/7.0/images/admin-ug/adddan.png\")
\nOnce assigned you can find Daniel in the list of members. At any time you can remove a member by clicking on the three dots (see example below)
\n![\"removedan\"](\"/7.0/images/admin-ug/removedan.png\")
\nInviting members
\nAs mentioned above, having an account created on id.almato.com is mandatory to get access to a Bardioc 7 instance. The invite members tab allows you to invite new members by providing their company email and as a batch upload using a csv file. Every invited user will be sent an email with an account registration link they must follow to activate their profile.
\n![\"invite\"](\"/7.0/images/admin-ug/invite.png\")
\nThe guides contain all the essential information needed for Subject Matter Experts (SMEs) and Knowledge Experts to teach Bardioc™ how to automate tasks.\nThey provide an overview of the Bardioc™ world, interaction guidelines for best results, and hints and tips on navigating the user interface for each role.
\n\n\n\n\n\n
\n\nSubject Matter Expert (SME) User Guide\nUsing Bardioc™ as a Subject Matter Expert\nSubject Matter Expert (SME) User Guide
\n
\n\n\n\n\n
\n\nKnowledge Expert User Guide\nUsing Bardioc™ as a Knowledge Expert\nKnowledge Expert User Guide
\n
\n\n\n\n\n
\n\nAdmin User Guide\nUsing Bardioc™ as an Admin\nAdmin User Guide
\n
\n\n\n\n\n
\n\nLearning Service Guide\nUsing Bardioc™ and Reinforcement Learning\nLearning Service User Guide
\n
The AI part of Bardioc is based on Reinforcement Learning algorithms.
\nReinforcement Learning is an aspect of Machine learning where an agent learns to behave in an environment, by performing certain actions and observing the rewards/results which it get from those actions.
\nThe algorithm (agent) evaluates a current situation (state), takes an action, and receives feedback (reward) from the environment after each act. Positive feedback is a reward (in its colloquial meaning), and negative feedback is punishment for making a mistake. Reinforcement Learning algorithms learn how to act best through many attempts and failures.
\nThe current implementation of Reinforcement Learning in Bardioc uses so-called Monte Carlo methods.
\nTo make Reinforcement Learning working successfully, we need to follow some basic rules when creating issues and writing KIs.
\nFirst, lets introduce some RL-specific concepts and notations:
\n![\"Reinforcement](\"/7.0/images/rl-ug/reinforcement_loop.png\")
\nAn Episode in Bardioc is called an Issue/Task.
\nBardioc is an Agent.
\nTo resolve an issue, Bardioc is interacting with an Environment.
\nA Time step consists of choosing and executing a single KI.
\nTherefore at each time step Bardioc is taking some Action (executing some KI).
\nAt each time step Bardioc is observing an environment. This particular observation at a particular time step is called a State.
\nOnce a KI is executed, Bardioc can obtain some Reward (numerical value). It is not necessary that a reward is received at every time step.
\nOnce the reward is obtained, Bardioc can (but not necessarily) observe a New State. When the issue is resolved in this step, this will be the Final state.
\nBardioc takes steps until the end of the episode/issue is reached.
\nThe main goal is to maximize the total reward and to make sure we take the most promising steps (execute the best possible KIs).
\nA short description of this process could look like this:
\n`state => action => reward => nextstate => action => reward => nextstate => … => action => reward => finalstate`\n
An example to illustrate this is the famous Tower of Hanoi.
\nEach disk can use one particular rod. That will be the State.\nWe can represent the state as a string:
\n![\"Hanoi](\"/7.0/images/rl-ug/hanoi_start.png\")
\nAll three disks are currently using the first rod. This state can be represented as HanoiPos_1_1_1
![\"Hanoi](\"/7.0/images/rl-ug/hanoi_mid.png\")
\nTwo disks are using the first rod and the third disk is using the second rod. This state can be represented as HanoiPos_1_1_2
To train the system to finish the task as fast as possible, we assign a reward of \"-1\" for each time step.
\nThe Reward is crucial for our system to work correctly. We can obtain the reward directly from the environment or from the KI. In the last case we should increment the ogit/RL/totalReward variable by this local reward.
ogit/RL/totalReward = ogit/RL/totalReward + local_reward
To penalize some action we can use a negative reward:
\nogit/RL/totalReward = ogit/RL/totalReward + (-local_reward)
The main idea is to encourage good actions/KIs and penalize bad actions/KIs, when it is possible. This approach is critical for Bardioc and its Learning Service to learn optimal behavior. If you don_t provide any reward during the whole Issue/Episode, the system will not be able to learn anything useful from this episode.
\nAnother example is the MAZE environment:
\nThe Episode starts at some initial point and ends when we move to the exit.
\nThe Environment is the whole gridworld/maze, where we can navigate our agent from one state/position to another.
\nThe State can be represented as the current coordinates (X, Y) or just as a number 1,2,3..,N. We always store the current state internally.
\nThe Reward is a numerical value, which is given to our agent via KIs. In case of maze, after each time step Bardioc gives the reward \"-1\" to our agent. By maximizing the total reward we are able to find the shortest path to the exit (e.g. our final reward is -100, which means it’s 100 steps, and that’s better than the reward -200, which is 200 steps). We store all the rewards obtained for each time step.
\nThere are two main variables in the Reinforcement Learning workflow:
\nogit/RL/totalReward
ogit/RL/state
Both are controlled via KIs.
\na) Use ogit/RL/totalReward when you need to encourage or penalize a particular KI.
If you need to treat your KI as an agent_s step, you should explicitly add some reward inside of this KI.\ne.g. in the KI definition, inside of the DO section:
ogit/RL/totalReward = ogit/RL/totalReward - 1
This will add a reward of -1 to this action/KI, it therefore penalizes this KI.
For example, in case of Maze or Tower of Hanoi, just use ogit/RL/totalReward = ogit/RL/totalReward - 1 for each KI so that you penalize extra steps taken and make Bardioc to learn the shortest path.
b) Use ogit/RL/state when you need to set or change your current state.
Defining a meaningful state can be tricky. You need to think about what combination of environment parameters can be used as a state. For example, in a Maze environment a state can be just a X and Y coordinates (e.g. a string “22_15” which represents x=22 and y=15).\nIn Tower of Hanoi this will be HanoiPos_1_1_1, where each \"1\" represents a disk using the first rod.
Example of a KI using the Reinforcement Learning system:
\n![\"SME](\"/7.0/images/SME-icon.svg\"){kind=icon}
![\"AIE](\"/7.0/images/AIE-icon.svg\"){kind=icon}
![\"Admin](\"/7.0/images/Admin-icon.svg\"){kind=icon}
![\"Dev](\"/7.0/images/Dev-icon.svg\"){kind=icon}
![\"support](\"/7.0/images/support-icon.svg\"){kind=icon}
![\"sme](\"/7.0/images/sme-guides.svg\")
ki\n id: \"HN3_R1\"\n version: \"0@rs\"\n description: \"Move disc 3 to position 1.\"\non\n ogit/_id\nwhen\n MakeMove == \"Hanoi 6.2\"\n DiskPos[1] as DP1\n DiskPos[2] as DP2\n DiskPos[3] != 1\n StepCounter < 1000\n ogit/RL/totalReward\n ogit/RL/state\ndo\n DiskPos[3] = 1\n ogit/RL/state = \"HanoiPos_${DP1}_${DP2}_1\"\n ogit/RL/totalReward = ogit/RL/totalReward - 1\n StepCounter = StepCounter + 1Sometimes there is only one state, depending on the issue. In this case the Learning Service will optimize for the number of KIs which were executed during this issue. It means that the Learning Service will try to choose those KIs which will help us to finish the issue faster, with a lower number of timesteps. Another approach is to choose only KIs which produce higher rewards.
\nA good example of a single state issue is a Multi-armed bandit problem.\nThe state is always the same, but the actions are different (one action for each bandit). The goal is to choose the best actions and get the highest total reward from these actions.
\nThere are times you need to submit a support ticket. In this section, we will provide some best practices to assist you in submitting the support ticket effectively.
\nWhen you find bugs and need to contact support team, please send us an email to support@bardioc.almato.com providing as much of the following information as possible:
\n[Subject]: Customer Name / Issue Description
[Body]:
Haas Instance ID:\nProvide haas ID
\nScenario (Please use one request per issue):\nDescribe what you were trying to do in a nutshell
\nSteps to replicate:\nList the steps to replicate the scenario as described above in a chronological order, including URI’s, tabs, or field labels etc.
\nCurrent result:\nDescribe your observation and attach log files and/or screen shots to illustrate
\nExpected result:\nDescribe what should have happened instead of what has been observed
\nEnvironment:\nIs the issue happening on the Production or Development environment?
\nPriority:\nHigh - Medium - Low
\nTimestamp:\nPlease provide timestamp for the event that worked and the one that didn’t work
\nTask Id:\nPlease provide Task id when applicable
\nPlease provide following details if you are facing any of these issues:
\n\"Bardioc is not processing incoming tickets\"
\n- Can you see the task on the \"Task Inspector\"?
\nWhich is the status of this Task in the \"Task Inspector\"
\n-How is the Task created (JIRA, SNOW, Postman)?
\nPostman: Please attach body request data details
\nJIRA/SNOW: Please attach Ticket id from your ticket System
\"The AH is giving errors/no working\"
\n- Which AH is not working?
\n Is the AH running \"on premise\"or cloud ?
\n Please provide Task id and correspoding Engine log
\n Has the AH worked before? Please attach Task id where the AH was working
\"I can not access to my Bardioc instance\"
\n- Please provide screenshot of the error message you get
\n- Please provide username you are using
\"Bardioc Apps are not working/ not accessible\"
\n- Which App is not working?
\n- Which username are you logged in?
\n- Please provide screenshot of the error/issue
\n- Which browser are you using?
\"My task resports \"terminated\"status\"
\n- Please provide Task id
\n- Has this Task worked before?
\"I can’t edit my KI\"
\n- Please provide KI id
\n- Can you access the K.I.M App?
\n- Which user are you logged in?
\n- Is the KI \"undeployed\"?
Where can I find the Task Id?\nGo to the Task Inspector App, select the Task. On the task Content Display, select “OGIT” and look for the value of the parameter “ogit/_id”.
\n![\"PictureTaskId\"](\"/7.0/images/request_support/PictureTaskId.png\")
\nWhere can I find the KI Id?\nGo to the Task Inspector App, select the Task. Now select the specific KI you want to know the Id and hover the mouse over the square box until you see the label “Open in Knowledge Item Manager”.
\n![\"PictureKIId1\"](\"/7.0/images/request_support/PictureKIId1.png\")
\nIn Knowledge Item Manager App, you can find the KI Id on the search box as well as on the ribbon of the KI.
\n![\"PictureKIId2\"](\"/7.0/images/request_support/PictureKIId2.png\")
\nWhere can I find the Engine Log?\nGo to the Task Inspector App, select the Task. On “View” menu select “Engine Log”.\nNow you can go to the KI you want to see the Engine Log from.
\n![\"PictureEngineLog\"](\"/7.0/images/request_support/PictureEngineLog.png\")
\nA KI, Knowledge Item, is an atomic representation of steps that is taught to Bardioc™. It is compounded by ON, WHEN and DO blocks.
\n![\"KI](\"/7.0/images/ki-syntax/KI_Structure.png\")
\nTechnically there is no difference between KIs, however, we can classify them in Action and Decision, to better optimize their usage.
\nAn Action KI performs a task on target systems via a command or script. They make use of Action Handlers to carry out these commands.
\nAction KIs are stand-alone actions broken down into their atomic form, created with re-usability in mind and independent of scenario. One concept that is very important on Action KI is the result interpretation, where we tell Bardioc what to do for the possible different command outcomes.
\n![\"ActionKI](\"/7.0/images/ki-syntax/ActionKI_BestPractice.png\")
\nExamples for Action KIs: Book Meeting Room, Request Holidays, Order Lunch, Update Timesheet.
\nA Decision KI contains and implements the expert logic of when certain actions should be taken for a Task-specific scenario.
\nIn order to keep Action KIs reusable, Decision KI do the checks which are Task-specific and decide when it is time to proceed to other Actions.
\nWe can spot the need for a Decision KI when an action is dependent on the outcome of successful run of another action, but only under certain conditions. In order to keep the Action KI reusable, these conditions need to be put into a Decision KI.
\n![\"DecisionKI](\"/7.0/images/ki-syntax/DecisionKI_BestPractice.png\")
\nExamples for Decision KIs: Decide to execcute a command in a Server, Decide to send email with train schedule, Decide to run server health check, Decide to inform user about ticket resolution.
\nA ticket sometimes will require different actions to be taken for it to be successfully completed. Meaning, a task may need to be broken down into many small, stand-alone and re-usable actions or sub-tasks.
\n“Parent” ToDo variable is the action that describes the scenario. This action keeps the Task active in processing state.
\nInitiate KI triggers before all other KIs and delegates sub-task by adding respective ToDo variables in the Task. It is the first KI, so it initiates automation and contains the “Parent” ToDo variable.
\nResolve KI triggers last for the specific scenario, ensures all required steps are taken and deletes the “Parent” ToDo variable, which should be the last one left on the Task. It indicates that the Task has been completed and therefore Task can be resolved.
\n![\"TaskFlow\"](\"/7.0/images/ki-syntax/TaskFlow.png\")
\nThere will be cases where dependencies between actions are needed.
\nCheck this PDF with the four following examples we have come up with:
\nOnboarding Employee
\nSend by email train schedule
\nDelete a user from a database and inform manager
\nUpdate Software
\nAgree on a set of rules within your team regarding Variable and KI naming conventions.
\nToDo Variables always start with a verb.
\nInformation Variables always start with a noun.
\nCamelCase is used for a variable name that combines two or more words. ToDo variables can start with a capital letter, and information variables with lowercase.
\nKI Title should be consistent with its contents (double-check this at the end).
\nKI Description should summarize Applicability, Situation and Action in one or two sentences.
\nThe KI title has \"and\", \"&\" or \"+\" in it. This typically indicates that the KI could have been broken down further.
\nThe KI Description is too simple. Descriptions should include a short summary of where and when the KI will trigger, and anything special about the way it runs (Send Email using Outlook, Gmail, mailx etc.).
\nThe ON block should not be too generic. “ogit/_id” causes too many unnecessary checks and delays. Instead, carefully consider Applicability and Availability for the ON section of each KI.
\nThe ON block should not be too specific. If an action may be useful elsewhere, then open it up by making more lenient conditions.
\nThe WHEN block of an Action KI doesn’t contain a check for the action’s respective ToDo variable. Each Action should work with a respective ToDo variable to indicate success/failure.
\nDO block begins with \"If…\" statement. At the beginning of the DO block there is no runtime data it could check for, but instead it can only see variables in the Nodes and Tasks, which means this criteria should have been checked either in the ON or WHEN block.
\nAction KIs are deleting the ToDo variable outside of an \"if…\" statement. Deleting a ToDo variable informs the Task that the specific action is done successfully. There will typically be conditions for this success and those should be covered in the \"if…\" statement.
\nTry to understand KI description as a whole (what is the SME trying to teach Bardioc? Don’t let the Variable suggestions sway you!).
\nWhen there are suggested KIs, always inspect those first to see if one could be reused for this same purpose.
\nOnly if none can be reused, create a new KI.
\nNever edit a deployed KI. If updates are needed, always create a new one with the revised execution commands.
\nStart with an Initiate KI.
\nIdentify the most relevant Parent ToDo name for the task to be resolved, so you can delete \"ProcessIssue\" as soon as possible.
\nCorrect breakdown of Steps into atomic KIs.
\nAction KIs are reusable.
\nDecision KIs are used effectively to allow for reusable Actions.
\nVariable declaration needs to be completed (wherever the SME has skipped this step).
\nManage only one ToDo per KI related to the step being executed. Check for its existence and delete it after successful execution.
\nEnsure robust result interpretation.
\nAre the criteria being used for result interpretation correct?
\nAre ToDo Variables being deleted at right time?
\nNo Variables used for substitution in DO block without having checked for them in the ON/WHEN block.
\nAre KIs reporting back results to the Task correctly (information variables containing output or status of an action).
\nNo unnecessary chaining of KIs (but dependencies between Actions are maintained, when necessary).
\nWhen re-using existing KIs, it is best to link them to the current teaching session for easy tracing(documentation as well as debugging).
\nWe have developed this\nguide to\nprovide an example of how to keep KIs atomic in the best possible way,\nallowing you to fully leverage the benefits of exponential teaching.
\nWhen writing Knowledge Items to convert SME knowledge for a new kind of Task (where all Steps are new to Bardioc), then debugging should be done by focusing on the KIs one by one in the order the SME taught the solution. Specifically, after writing each KI, it would be put to “Validation” mode to test that the conditions are correct. Once this is confirmed, then it can go to “Live” mode where its DO section is validated by creating a test Task in Bardioc, when possible. More details on how “Validation” mode works can be found here.
\n![\"PassiveValidation\"](\"/7.0/images/ki-syntax/PassiveValidation.png\")
\nFor a longer, more robust validation process, you can put your KI in Validation Mode and come back a few days later to check if you agree that your KI should have triggered each time that the Validator has logged it would. To check which Tasks your KI would have been applied on, had it been in Live mode, please open the Knowledge Item Manager and search for your KI on the top right. Select it from the list and you should see your KI contents on the right-hand side. In this view, you can select the tab next to the “Code” tab called “Validation Statistics” and select the time range that you’re interested in.
\nWith Active Validation, we can check whether the conditions of all our KIs together are as expected. After converting the Steps to KIs, we can put them all in Validation mode and create a Task to test whether the Validation capability will log anything. Typically, after this, we would expect only the “first” KI to have something logged in their Validation Statistics. If other KIs do too, then it means that they were just as likely to run first. If this is not a problem, then proceed as before. But if it’s not expected behaviour, please look into adding or editing some of the conditions in the ON and/or WHEN block of your KI.
\nThe reason that we put all KIs in Validation mode to begin with is to ensure our KIs interact with each other, but also existing KIs are triggered as expected. For example, if a Task triggers some existing KIs and after that matches the conditions of our new KI (the KI would not actually run, but it will simply be logged in Validation Statistics, just as above), then we would have to look into our KI and the Task to check whether this is intended behavior or not. In some cases, it may very well be what we expect, in which case the KI passed validation.
\n![\"ValidationStatistics\"](\"/7.0/images/ki-syntax/ValidationStatistics.png\")
\nIf the KI that was supposed to trigger didn’t log anything in the Validation Statistics that means that the conditions didn’t match with the Task contents at that point in time. In order to troubleshoot this, please see section “Conditions Check” below. So, the KI would be undeployed and edited as required. Once a KI has passed validation, it can go into “Live” mode. That means that the next time the Task comes in, the KI will trigger and carry out the action it describes. Now, the Task has changed, it’s this Task that will be checked for the remaining KIs which are in “Validation Mode”. That means that the “next” KI which is expected to run in this case should have this Task logged in its statistics tab in KIM.
\nImportant Note: KIs are not intended to be chained, so when referencing an order here, we always refer to the logical step in the solution. KIs can however be used in combination with other pre-existing KIs as well, so validation mode is a good way to “foresee” this, as we deploy the KIs one by one after passing validation.
\nIf you find that some KIs are not behaving as expected during validation, this means that something in the ON or WHEN block is causing the problem. Below you can see what to look out for in each block and the most common “mistakes” we’ve come across so far.
\nMake sure the conditions stated in the ON block are met by the Node on which your Task occurred (or traversed to – if this option has been enabled). To do this, please open one browser tab with the KI that you believe should have triggered (Knowledge Acquisition Tool or Knowledge Item Manager) and a second tab with the Task that it should have triggered on (in Task Inspector). In Task Timeline (left), go to the point where you believe your KI should have triggered and select the KI just before it.
\nOn the top right, please select the “Node” view from the dropdown list. Now you should see the contents of the Node that the Task was on at the time that you expected your KI to trigger. That means your KI should have:
\n(a) been present here,
\n(b) contain criteria the Task contents would match at this point in time
\nTherefore, we can begin debugging the ON block first, by looking at the Node contents on the right-hand side, in the new view that we just selected, and the KI contents, specifically the ON block. We are looking for any mismatch between criteria described in the ON block, and contents of the Node that we expect it to have been bound to. To get you started, you can have a look at the section below called “Most Common Problems”.
\nSteps:
\nOn Task Inspector, select View “Current Node”. On Task Timeline, go to the previous KI to the one that you believe you should have triggered.
\n![\"CurrentNode\"](\"/7.0/images/ki-syntax/CurrentNode.png\")
\nNow open K.I.M in another tab, look for the KI you believe it should have triggered and start checking if the variables on the ON block are matching the variables from the current Node.
\n![\"KIMApp](\"/7.0/images/ki-syntax/KIMApp_on.png\")
\nPlease have one browser tab open with the KI that you believe should have triggered (Knowledge Acquisition Tool or Knowledge Item Manager) and a second tab with the Task that it should have triggered on (in Task In-spector).
\nIn Task Timeline, go to the point where you believe your KI should have triggered and select the KI just before it. Here, we are seeing the Task contents for that exact point in time, meaning it is at this point that your preferred KI’s conditions (WHEN block) should have been met. Now, it’s time to compare the WHEN block against the Task contents (in the “Task Content Display” view).
\nSteps:
\nOn Task Inspector, select View “Task Content Display”. On Task Timeline, go to the previous KI to the one that you believe you should have triggered.
\n![\"TaskContentDisplay\"](\"/7.0/images/ki-syntax/TaskContentDisplay.png\")
\nNow open K.I.M in another tab, look for the KI you believe it should have triggered and start checking if the variables on the WHEN block are present in the Task Content Display and meet the matching criteria.
\n![\"KIMApp](\"/7.0/images/ki-syntax/KIMApp_when.png\")
\nEngine Log view can be found under Task Inspector and provides information on the result of the AH execution as well as on the output from the commands executed. This is especially useful to check if the AH has been exe-cuted correctly, and the return values from the command.
\nIf you face something like “action failed” , this is probably referring to AH issues itself, so you should contact support for help.
\n![\"EngineLog\"](\"/7.0/images/ki-syntax/EngineLog.png\")
\nOtherwise, you can look at the response from the command. Among the return values, you have a parameter that collects the error message(stderr) and this can give you an idea what the problem is. Maybe the command syntax is not correct, there is a typo, or the syntax format needs to be different to be accepted in the KI. More information about how to interpret the output values from the command, can be found here:https://user-guides.engine.datagroup.de/7.0/ki-syntax/functions/action/.
\n![\"EngineLogTaskStopped\"](\"/7.0/images/ki-syntax/EngineLogTaskStopped.png\")
\nYou can also try to find a Task that has been successfully resolved and compare the log with the Task that has been stopped. This way you can see if this AH has been working before and the expected output values from the execution of the command against the values you are getting in the stopped task.
\n![\"EngineLogTaskResolved\"](\"/7.0/images/ki-syntax/EngineLogTaskResolved.png\")
\nOpen your Desktop and navigate to Bardioc Graph Explorer
\n![\"BardiocDesktop\"](\"/7.0/images/ki-syntax/BardiocDesktop.png\")
\nIn top filter pane choose ogit/Automation and “Automation Issue”. You can choose to narrow down search by indicating Scope and Organization
\n![\"BardiocGraphExplorer\"](\"/7.0/images/ki-syntax/BardiocGraphExplorer.png\")
\nSelect a Task you are debugging
\n![\"BardiocSelectIssue\"](\"/7.0/images/ki-syntax/BardiocSelectIssue.png\")
\nInspect details on right hand side pane to check you KI matching conditions
\n![\"BardiocData\"](\"/7.0/images/ki-syntax/BardiocData.png\")
\nYou can inspect JSON Meta or Graph View to better understand existing Issue context and applying conditions.
\n![\"BardiocGraphView\"](\"/7.0/images/ki-syntax/BardiocGraphView.png\")
\nCase sensitivity error in Variables’ values that are being checked (e.g. Task says MyVar = “test1” and your conditions in the WHEN block are: MyVar == “Test1”)
\nTypos in Variables’ values that are being checked (e.g. Task says MyVar = “test1” and your conditions in the WHEN block are: MyVar == “tst1”)
\nWrong variable being used (e.g. ogid/_id, ogit/_name, ProcessMe vs process_me vs ProcessIssue etc.) Please ensure that your KI is using the same variable and spelling as in your Node or Task.
\nVariable source condition. Sometimes Variables have a source appended to them in the conditions e.g. MyVar@parent. This shows that the KI will only trigger if the Variable “MyVar” was given value when it was on the “parent” Node of the particular Node this KI is bound to. (default is @any and can be omitted)
\nUse of keys in conditions and not in original Task or vice versa
\nProblems with regex. In this case, it’s good to check the regular expression being used first outside of Bardioc, then implementing it here.
\nLooping. This can occur when a KI has conditions in the WHEN block that are relatively lenient and their KI doesn’t change anything on the Task that would directly affect the variables from the WHEN block.
\nUse of unlimited “counters”. Optional matching is often used for counters when writing a KI that we intentionally want to trigger more than once. However, we should define a limit to this looping, and that’s done by including a condition in the optional matching as shown in the example below. Here we’ve implemented the logic “Condition is true if the variable ‘Count’ exists and is less than 5, or if it doesn’t exist we will initialize it to 0, meaning Counter == 0” → ? Count < 5 := 0
\nLogical error in conditions (this occurs in various ways, depending on Task and solution provided by SME)
\nIf you can’t detect any reason why your KI has not triggered, you can edit the KI by commenting out each line in the WHEN block except the first. Then put this KI in Validation Mode and insert a (test) Task with the exact same contents the Task before it had at the point in time when you expected your KI to trigger. (You can do this also in Live mode if the KI is simple and won’t cause any harm during testing.) Keep an eye on the Validation (or Live) Statistics and confirm that the Task you just inserted would have triggered your KI, which now only contains one condition. If yes, proceed with uncommenting the second line and repeating the process.
\nWhen you reach a point where the KI isn’t logging (or triggering) for the exact same Task, then this condition needs to be revisited. Comment it back in and proceed with the checks for the other lines in the WHEN condition. This way you will identify if there’s more than just 1 condition not being met which will help during debugging, as we troubleshoot only one of the detected “faulty” lines at a time.
\nFor the line that keeps the KI from triggering on your Task, please look through the list above to help troubleshooting. If you still can’t spot what the problem may be, read through the Documentation for the specific matching syntax that you’re using. If it’s a very straight forward condition, then the problem may also be on the Task itself. Check Task contents to ensure there’s no typo related to this condition, and that it matches it perfectly, before trying again.
\nKI Syntax is a formalization language for knowledge around automating processes. It is the basis for the Knowledge Items (KI).
\nThe assumption is, the system will have access to the same information as any (privileged) user and needs to be taught how to interact with the data in order to solve \"Issues\". KI Syntax describes logic that processes/gathers/generates data in a certain way to contribute to the overall problem solution. This logic is stored in the Knowledge Items. Bardioc Engine applies Knowledge Items to its tasks.
\nApplication of Knowledge Items works by matching data to KI that call for these conditions and associating the KI to these data points. This is called \"binding\". At any time many Knowledge Items can be \"bound\" to the same data.
\nA task is stored in a theoretical data container called an \"Issue\", this includes the current state of data gathered/generated for this task and the history of steps and changes made to the data during processing.
\nA very simplified Issue could look something like this:
\n{\n \"/Subject\": \"MyTestIssue\",\n \"/MyVariable\": [\"FirstValue\", \"SecondValue\"]\n}Bardioc will apply Knowledge Items to an Issue until the task is completed or it runs out of applicable knowledge. In such a case Bardioc will attempt to draw in knowledge from surrounding nodes to further work on the Issue or in rare cases eject the Issue for processing by a human. A task is considered completed when all todo variables are empty/removed.
\n| \n\n | \n\nYou should have a look at our Useful tips section\n | \n
While KI Syntax borrows heavily from common programming language features like string expansion or comparison operators, it should not be confused with a programming language. KI Syntax purposefully does not natively support creation of large monolithic algorithms. The goal is to write atomized bits of knowledge that can be freely strung together by their inputs and outputs and are as re-usable for as many use cases as possible.
\nYou can, however use the included math, JavaScript and Regular Expression functions to manipulate data in your Knowledge Items.
\nThe syntax is defined by the structure of KI described in this document and the available KI Syntax functions.
\nKI Syntax is written as simple text using a YAML-like approach with a 2 spaces (` `) indentation pattern.
\nFor example:
\nki\n name: \"Test\"\non\n A\ndo\n log(\"we have an A with value ${A}\")Bardioc™ is an automation tool based on artificial intelligence, created by Almato. It can be used to automate both IT and business processes, enabling companies to utilise time and resources effectively.
\nKnowledge is taught to Bardioc™ in small pieces that contain the context in which they can be used. Then, when a Task is assigned to Bardioc™, it will try to solve it by recombining all the knowledge it’s been previously-taught based on the Task context at each given point in time. This means that Bardioc™ doesn’t learn in strict workflows like, for example, scripts. Instead, it will create a workflow in real time as it evaluates the Task context and, based on that, decides on the Steps to take on the fly.
\n![\"Steps](\"/7.0/images/sme-ug/Bardioc7/KI_selection.gif\")
\nBardioc™ integrates into your environment in order to receive Tasks, the same way that you do! For example, these may be in the form of ITSM Tickets that are assigned to you, or submitting of forms, even e-mails. Integration is the first step because these Tasks will now all be \"delegated\" to Bardioc™, and only when Bardioc™ can’t solve it, it will come to you.
\nA simple look at the process is as follows:
\nTicket/Task is assigned to you
\nYou briefly check what Bardioc™ has already done to detect which steps are missing from the solution
\nYou solve the Ticket manually
\nYou locate the Ticket in Bardioc™ Tasklist and press Start Teaching
\nYou explain all the steps you took to Bardioc™ Chatbot in natural human language
\nThe chat is converted to code that Bardioc™ understands and will use next time to solve the Ticket autonomously
\n![\"SME](\"/7.0/images/sme-ug/Bardioc7/SME_workflow.gif\")
\nThe first few times Bardioc™ is delegated a Task, it won’t be able to do anything to solve it, as it hasn’t been taught anything yet. Which means you would have to solve the whole Task manually. Once solved, the Task needs to be located in the Bardioc™ Tasklist with a simple search, and you can then begin teaching Bardioc™ the steps you took to solve it, so that next time it can do it autonomously.
\n![\"Bardioc](\"/7.0/images/sme-ug/Bardioc7/SME_01.png\")
\nTeaching Bardioc™ is made simple with the help of a chatbot, which will guide the knowledge transfer by asking questions regarding your Task solution. Once you’ve completed the chat, you can ask your peers to review your solution, and then hand over the full chat conversation to a \"Knowledge Expert\", who will convert this into a format Bardioc™ can understand and apply to future Tasks.
\nBardioc™ is always working in the background, whether that be carrying out tasks, or learning how to automate new ones. This can be seen in the two modes Bardioc™ works in:
\nBardioc™ solves tasks automatically by applying pre-existing knowledge.
\nBardioc™ gets taught new knowledge to automate new tasks in an agile manner.
\n\nPrimarily, Bardioc™ needs to understand the environment that it will automate in, including which tasks can occur there. These can both be extended as the scope grows, but to start off one should select an end-to-end process to automate, and define which tasks can occur there and their triggers.
\nTriggers will be defined for each problem type, and an Automation Task will be created in Bardioc™ every time a trigger is detected. In the Automatic Execution Mode, Bardioc™ tries to solve each task by applying existing knowledge that it will have been taught previously.
\nIf the knowledge present is not sufficient for a specific task, Bardioc™ will request to be taught new knowledge in the Agile Automation Mode, so that it can solve the task automatically the next time a similar trigger occurs.
\nAutomating with Bardioc™ entails indirectly collaborating with various team members that will each use Bardioc™ differently. For this purpose, Almato has created some User Roles to better separate responsibilities, processes for hand-over, and allow for the user interface and training content to be better catered to each role.
\nA Bardioc™ Developer is responsible for creating and configuring the Action Handlers and Connectors planned in the Solution Design phase. They are familiar with the source and target systems, and the available Bardioc™ APIs.
\nExperts who will teach Bardioc™ how to automate processes they are knowledgeable on through a chat conversation where they answer some questions regarding said processes and tasks within them.
\nThis role will be given to users who understand how Bardioc™ works, and can edit Bardioc™'s' automatically generated code to ensure it has translated content from an SME’s chat conversation correctly into KIs.
\nThis role will be given to users who understand how Bardioc™ works, permissions required for each user, and how to configure this using Bardioc™ User Interface.
\nBardioc™'s entry point is the Dashboard, where you can see at a glance the status of your Bardioc™ instance. At the top we’ve got counters for Tasks that are new, already started, and those pending to be reviewed. Clicking on these will take you to the respective list of Tasks. On the right, we have statistics of your Automation Rate (Tasks received / Tasks automated), and counters for your automated Tasks and knowledge that Bardioc™'s been taught.
\n![\"SME](\"/7.0/images/sme-ug/Bardioc7/SME_02.png\")
\nThe view on the bottom left is where we can see the most recent Tasks that Bardioc™ was not able to solve, and those that have been assigned to us for peer review. If you already see the Task you wish to teach here, then you can directly click the button to start teaching, but if not, then you can have a closer look by opening the Task List.
\n![\"Task](\"/7.0/images/sme-ug/Bardioc7/SME_03.png\")
\nThis is where you will see all the Tasks that Bardioc™ could not solve, and their status. If a Task has already been handed over, or another teammate has ownership of the teaching session, you are only able to \"visit\" the session. So, you will not be able to make any changes. You also won’t be able to make any direct changes to teaching sessions that have been assigned to you for peer review - but you can comment on many things in the session such as the overall solution or a specific reply to a chatbot question regarding a single step.
\nIf you know the exact Task you want to teach to Bardioc™, you can search directly for the ID, Task name, or part of it on the top right corner. This view also allows you to filter what shows up in the list by Task type, status, or ownership, in case you would like to manually look for a group of Tasks. Once you’ve located your Task, press \"Start Teaching\" and this will take you to the Knowledge Acquisition Tool (KAT) to begin the knowledge transfer.
\nThe Knowledge Acquisition Tool (KAT) is where SMEs can teach Bardioc™ how they solved a specific Task. Bardioc™ chatbot asks questions to guide the SME through the process of creating a full teaching session containing all the information Bardioc™ will need to automate the solution. The first question aims to break down a solution into small Steps, then for each Step a new tab is created where Bardioc™ will ask more specific questions and the user can answer them in a more focused \"sub-chat\".
\n![\"KAT](\"/7.0/images/sme-ug/Bardioc7/SME_04.png\")
\nWhen answering the first question, the SME must list each step that they took and type done at the end. This is so that Bardioc™ knows when the list is complete and can proceed to more detailed questions. The Steps should be worded as an action, rather than recollection (\"check disk space\" instead of \"I checked the disk space…\") Most importantly, it’s natural when listing steps that solved a problem to also list the navigation, such as \"Open Outlook…\"\" or \"Go to website…\" or \"Start the Application…\", but when it comes to teaching Bardioc™, each Step is defined separately, so the information about where it’s carried out will be explicitly included in each respective step. This means that when listing the Steps they took to solve a Task, an SME needs to beware that they don’t list any step which is only showing navigation.
\nFrom here, a new tab will be created for each Step listed and the SME can proceed to the more detailed questions in the \"sub-chats\". For each question, there’s a button available which shows the best practice that can help provide direction and examples for the SME’s reply.
\n\nThe first question in a sub-chat requests a description of the Step, which would include more detail that the Step title. If the title itself is straight-forward enough, then the SME should re-word it here for the description. This will be helpful as it covers 2 ways of saying the same thing, so when Bardioc™ tries to match this Step later to existing knowledge that it can offer for re-use, it will be more likely to correctly match knowledge based on title and description.
\nThe second question refers to the \"location\" where the action was carried out and how this was determined. It could simply be an application name (such as a specific ERP system, monitoring tool etc.) or a specific server name. The SME must include in their reply the information as to why this is the place to run the certain action. This could be because: it’s the only application that allows this action (e.g. if the action is sending an email, a company would typically use only 1 specific application for it), or because something in the Task hinted at this particular location (e.g. if the user that put up the request belongs to a certain team and this tells the SME that the action necessary needs to be carried out on a different location to usual), or even directly referenced it (e.g. the Task contains the name of the affected server or application).
\n![\"Sub-Chat\"](\"/7.0/images/sme-ug/Bardioc7/SME_05.png\")
\nNext, the SME is asked to describe the reasons why they decided to carry out this Step. This could be as simple as explaining that the Task description contained the words \"server\" and \"unreachable\", which made them restart it, or explaining that they sent an email because they found from a previous Step that the user did not exist. So, the timing of the Step is what’s primarily provided here and, along with that, what content from the Task was used for the Step. This is referring to fields in the Task, such as checking whether a user exists by extracting the username from the \"email\" field in the Task. So, the third question is asking for all the information from the Task that indicated it’s time for this particular action to run, and also all the information that was extracted from the Task and used in the action itself.
\nFinally, the Bardioc™ Chatbot asks the SME to provide the exact details of the action. This can include navigation through an app or exactly which buttons to press (e.g. I clicked on Admin, then opened the edit tab… etc.), the command itself, when available, and the details as to how the SME realized the action had been successful (e.g. the pop-up showed \"Done\", the command returned the current free disk space in GB etc).
\nOnce these questions are answered for each Step listed at the beginning, the chatbot will prompt the user for either adding more knowledge, requesting a review from a colleague, or handing the teaching session over to a knowledge expert for coversion.
\nOnce a Teaching Session is complete an SME can request a peer review from another colleague as a way of confirming their knowledge and that all details are included. Reviewers can be added by clicking on the icon at the top right of the screen in KAT, and typing in the names of the colleagues who will review and press OK.
\n![\"SME](\"/7.0/images/sme-ug/Bardioc7/SME_06.png\")
\nThen, the SME is notified when the review has been completed. The comments added by reviewers will be visible in the screen on the right, and the Teaching Session owner can choose to reply to the reviewer comments, make the suggested changes and resolve the comments, filter, sort,edit, delete etc.
\n![\"SME](\"/7.0/images/sme-ug/Bardioc7/SME_09.png\")
\nWhen a user replies to a comment, they have the option of tagging someone by using the \"@\" symbol and then their name. This will show up to the person who was tagged as a notification and a comment pending reply. When the owner of a session changes something that a comment by the reviewer is referring to, that comment is then marked as \"outdated\" and can be filtered out by clicking the icon at the top right, and unchecking the box. Here one can also sort the comments in the order they prefer.
\n![\"SME](\"/7.0/images/sme-ug/Bardioc7/SME_08.png\")
\nWhen a Teaching Session has been assigned to an SME to review, they will receive a notification by Bardioc™, and it will appear on their Bardioc™ Dashboard. First the number will change at the \"Tasks to be Reviewed\" counter, and the Teaching Session will also be available at the top of their Task List. Once they click to start, they’re taken to KAT, in \"Review Mode\". This can be seen at the top right, next to the Teaching Session name, there will be a title \"Review Mode\", and also the colour scheme is different to that of SME view and Knowledge Expert view.
\n![\"SME](\"/7.0/images/sme-ug/Bardioc7/SME_07.png\")
\nThis KAT also has a comments pane on the right hand side of the screen. Here, a reviewer can add general comments about the Teaching Session. They can also add comments by clicking on the speech bubble icon wherever available (please see list below) if they wish to be more specific about their review point.
\nA Reviewer can comment on:
\nThe Teaching Session as a whole
\nA specific Step
\nA reply to a chatbot question within a Step definition tab
\n![\"SME](\"/7.0/images/sme-ug/Bardioc7/SME_10.png\")
\nA review will show up as complete to the owner as soon as the first comment has been added. This is because the process can be a continuous back and forth as owner and reviewer(s) can reply to each other in the comments. When there’s multiple reviewers, one can also distinguish who they’re referring to by tagging someone in a comment. This can be done simply using the \"@\" symbol and then their name. This will show up to the person who was tagged as a notification and a comment pending reply.
\nThere are two sides to reviewing a Teaching Session. The first is confirming that the expert knowledge that is being taught to Bardioc™ is correct and complete. The second is, ensuring that it’s a good Teaching Session. This can be done with the help of checklists and best practice which can be gained through training and experience.
\nWhen the owner of a session changes something that a comment by the reviewer is referring to, that comment is then marked as \"outdated\" and can be filtered out by clicking the icon at the top right, and unchecking the box. Here one can also sort the comments in the order they prefer.
\nThe first page we see when accessing Bardioc™ is the Dashboard, which presents us with a lot of information regarding the relevant Bardioc™ instance. Here we can find the number of Tasks that are still open and need teaching, Tasks that the user has left incomplete, and Tasks that are pending review.
\n\nOn the top right it shows the statistics about the instance such as the automation rate, and the number of successfully automated tasks, along with the knowledge that is currently in the system. In the view on the bottom left the is a preview widget of the Tasklist. Here, the SME can see the titles of the most recent Teaching Sessions relevant to them, either because they’re pending review, have already been started by them, or simply are new Tasks that are waiting to be \"picked up\" by an SME to teach Bardioc™ how to solve it.
\n![\"SME](\"/7.0/images/sme-ug/Bardioc7/SME_11.png\")
\nBy clicking on buttons next to specific teaching session such as (\"Review\", \"Start Teaching\", \"Continue Teaching\" and \"View\") the SME is directed to the Knowledge Acquisition Tool (KAT) where they can work with the chatbot to teach Bardioc™ new knowledge. If the user prefers a larger view, they can press the \"Open Tasklist\" button and will be directed to the Tasklist where they can view the full list of Tasks that Bardioc™ couldn’t solve autonomously, and can search or filter by status, group, or ownership.
\nThe Dashboard also allows a user with both roles to switch between SME and Knowlge Expert view, simply by changing it on the top right. Next to this is also the selection of Bardioc™ instance. An organization may have more than 1 Bardioc™ instance at a time, and by clicking the dropdown list at the very top right, a user can switch between both views.
\nThere are 2 types of user roles one can have in Dashboard, based on how they are expected to teach Bardioc™:
\nSMEs: who will teach Bardioc™ how to automate their tasks using a chatbot
\nKnowledge Expert: who will peer review Bardioc™ automatically generated code, which is based on SME chat conversations
\nso it’s best to check that the right permissions have been granted before continuing. This can also be done by clicking on the Profile icon on the top right, and seeing the User Role in the View Profile section, as shown below.
\nThe Tasklist serves as a type of a \"ToDo list\" for both SMEs and Knowledge Experts. Depending on the role different filters and views are available. Start Teaching, Start Conversion, View Teaching, Start Review all take the user to the Knowledge Acquisition Tool where they can teach Bardioc™ the steps needed to resolve an Automation Task or review a colleague’s Teaching Session.
\n\nThe filters in Tasklist are shown all by default. The meaning for each can be found below.
\nMy Tasks:\nAll Teaching Sessions with your specific user as Knowledge Owner.
\nMy Teams Tasks:\nAll teaching sessions from users within the same organisation.
\nArchived Tasks:\nAll archived tasks. (Archiving can be done using the 3 dots at the end of a row. Once archived they can be restored.)
\nMy Review Tasks:\nAll of Tasks that you have requested peer review for.
\nMy New Review Tasks:\nAll of Tasks that peers have assigned to you for review and you have note yet begun.
\nNew Tasks:\nAll Tasks that Bardioc™ wasn’t able to solve and need teaching.
\nThe Knowledge Acquisition Tool is how knowledge gets inserted into Bardioc™. The SME will do this by talking to a chatbot, so their KAT user interface looks different to that of a Knowledge Expert’s. The SME will be directed to KAT from the Tasklist app, where they will select an Automation Task to teach Bardioc™ about, by starting a teaching session. Then they are redirected to the Bardioc™ Knowledge Acquisition Tool where they can re-name their teaching session (teaching session typically takes Task name) and begin describing the steps they took to complete the task at hand.
\n\nWhile the SME is listing the steps they took, KAT creates tabs in the background for each one. This way it allows for sub-chats to be created where each step can be defined in more detail and the teaching session is visually more organised to increase readability.
\nThe chat conversation between Bardioc™ and SME will be used to create Knowledge Items which a Knowledge Expert will later review, and input into Bardioc™ so that the steps in question can be automated, and carried out by Bardioc™ in the future. Bardioc™ engages with SMEs to learn how they solved a specific problem. With a predefined and ever-growing vocabulary, Bardioc™ Chatbot is able to understand and interpret natural language to generate machine-readable code for the Knowledge Expert to review.
\n![\"SME](\"/7.0/images/sme-ug/Bardioc7/SME_12.png\")
\nOnce each step has been described thoroughly by answering the chatbot questions, which will also define where and when each step can be applied, KAT offers the SME the option of doing the final check and handing the teaching session over to a Knowledge Expert for automatically generated code review.
\n\nIt is important to note that once a teaching session is handed over, it can only be viewed by the SME. The progress bar will provide them with a status on how many steps were created, which Knowledge Expert is working on the conversation and, eventually, how many KIs have been deployed.
\n\nBardioc™ Chatbot aims to extract information regarding the steps to automate a certain task that it was not able to automate before. Which means that, ideally, each teaching session will begin with a Task that has been \"stopped\" and was not automatically resolvable by Bardioc™.
\nFrom each step Bardioc™ is trying to learn where it can apply this knowledge (in the case that there’s environment data present which limits its application), and when it can be applied, meaning what information does the task definition need to contain for this step to be carried out. Lastly, Bardioc™ tries to extract exactly how it can recreate that specific step when the time comes.
\n\nThis information is crucial to the Knowledge Expert as well as Bardioc™ Chatbot, as they will review the automatically generated code, and edit when needed, so it’s of great importance that each step is described thoroughly. At the beginning of each 'sub-chat', Bardioc™ asks for a description of this step. This allows others to understand what the KI does, at a later point, when it may be suggested for re-use in a different teaching session.
\nBardioc™'s own \"language\" consists of Variables. These are keywords that Bardioc™ uses to understand the automation environment and to allow all related components to \"communicate\" with each other. Because Bardioc™ will see Task contents as a list of Variables, it’s best to provide the names of the fields of interest in a ticket or Task, so that Bardioc™ can work with the correct content during conversion of natural human language to code.
\nFor best results in chats-to-code translations, it’s important to keep in mind the below principles when interacting with Bardioc™ Chatbot.
\nBase your teaching session on a Task that you have manually resolved\nThis way the knowledge taught is based on experience alone, and knowledge added is required for a certain task that has already been attempted by Bardioc™.
\nTeach Bardioc™ the exact steps you used to manually resolve the problem - exceptions can be added in separate teaching sessions\nBy doing this you ensure that you follow the \"happy-path\" logic, where you describe steps and reactions to real outcomes, rather than over-planning a solution imagining each possible outcome of an action and preparing for said outcome.
\nRetrace the steps that you did manually and list them clearly at the start\nThe very first question that Bardioc™ Chatbot asks requires the SME to list the steps they took. Each of these steps will be turned into a Knowledge Item, that Bardioc™ will use and recombine in various ways. This is why they must be clearly listed so that they can also be re-used by other teaching sessions when they are describing similar steps.
\nInclude even the smallest decision or action\nWhen teaching a colleague how to do a task, a lot of information can be implied. When it comes to teaching the machine, all information regarding an action and why you decided to take that action, should be explicitly included in your teaching session.
\nTeach Bardioc™ in an “atomic” fashion, i.e. every small step of your actions or decisions separately\nIt’s important to cover all the steps, and to break them down in a way that they are atomic and easy to teach. This atomicity is also very important when it comes to knowledge re-usability, as Bardioc™ will re-combine knowledge to find a solution, and this is easier and more effective when we have atomic pieces of knowledge.
\nBe precise in your descriptions and do not leave room for wrong interpretations\nAt the end of a teaching session you will be asked to hand over to a Knowledge Expert who will review the automatically generated code. For this to go smoothly they need to fully understand each step, with only your descriptions as input, which is why it’s crucial that you’re thorough and precise.
\nAim to use the same language Bardioc™ already knows (use suggested variables whenever feasible)\nAs you answer questions, Bardioc™ tries to map the natural language to its own vocabulary - variables. Reusing existing variables allows Bardioc™ to understand the world and combine new and existing knowledge to solve problems.
\nA task will be described in Steps, and each of these Steps will be 'translated' into Knowledge Items (KIs), which is what Bardioc™ uses to automate. Knowledge is described with the focus of covering 3 aspects:
\nWhere?
\nWhen?
\nWhat?
\nThese 3 questions can be used to sufficiently describe any action, and the answers to them will be mapped to the structure of a KI, which is:
\nOn
\nWhen
\nDo
\nOne can think of any piece of knowledge as a sentence using the 3 sections of a KI. Examples below:
\n\"On the market, when it’s raining, I open my umbrella to cover my head.\"
\n\"On the treadmill at the gym, when I’m out of breath, I lower the machine speed\"
\n\"On the train, when a ticket inspector comes to my seat, I show my ticket\"
\nSteps of a task or process described to Bardioc™ should also follow the same logic. Through the chat prompts, Bardioc™ tries to understand where the knowledge being taught is to be applied, under what conditions can it be carried out, and what exactly the action is, and how it can be done.
\nIn Bardioc™ however, the entities used to describe the On and Where of a certain piece of knowledge will probably already exist in Bardioc™ and will have been described in the form of Variables. So when answering the question \"Where can this knowledge be applied?\" one should consider the answer in natural language, then look into the suggestions to see what Bardioc™ has mapped it to, and if the terms match.
\nThe second part of a KI will define when a certain action can be carried out. This translates into Bardioc™ in the form of conditions that variables need to fulfil. For this part, it’s good to keep in mind what information is needed for the action to be carried out (e.g. one needs an email address, email body and subject to send out an email) and what the action’s trigger is (i.e. how did the SME know that it was time to send an email at this point in the process).
\n\nLastly, the Do section of each step will be where an SME can describe the way in which they carry out the action stated in the title. This description can also include methods, special equipment to be used, and any other peculiarities there may be depending on the step. But most importantly, it’s also good to describe at this point how one defines success for that specific action. A Knowledge Expert will write this knowledge with minimal knowledge of the actual daily tasks of an SME, which is why it’s very important to also share how Bardioc™ can check the result it will get each time, for the result interpretation part.
\nEach Do part of a Knowledge Item should end with result interpretation, which is where Bardioc™ 'translates' its findings after each KI run. For this, the SME needs to explain what is cosidered a 'successful' run, and how to interpret that so other knowledge can react to this new changed state.
\nOnce each step has been described thoroughly by answering the chatbot questions, which will also define where and when each step can be applied, KAT offers the SME the option of doing the final check and handing the teaching session over to a Knowledge Expert for automatically generated code review.
\n\nIt is important to note that once a teaching session is handed over, it can only be viewed by the SME. The progress bar will provide them with a status on how many steps were created, which Knowledge Expert is working on the conversion and, eventually, how many KIs have been deployed.
\nThe Bardioc™ User Interface hosts applications that enable users to automate Tasks based on their User Role. From here, a Subject Matter Expert (SME) can navigate to their Tasklist app, and look at the list of Task which are not yet automated.
\nThey can select a Task to start a Teaching Session, which will redirect them to the Knowledge Acquisition Tool (KAT), where they can teach the Bardioc™ Chatbot in natural language what Steps are needed to automate that Task.Once the teaching is complete The next time that the same Task occurs, and this Task needs to be completed again, it will be fully automated!
\nBy clicking on the drop down icon on the top left, a user can switch between apps as needed. For more user-specific details,on the top right there’s a button with a grey smiley, where one can find their profile, documentation, account settings and more.
\n![\"smed](\"/7.0/images/sme-ug/smed-2.png\")
\nAs Bardioc™ Dashboard is tailored to the user for a more customized and smooth automation experience, it’s important to know which User Role is selected for your profile. This can be seen in the Account Settings view, by clicking the View Profile button. From here, one can see their username, User Role, and can choose to change their password. More details on User Roles can be found here.
\n\nThe Tasklist is where an SME can see the Tasks that Bardioc™ could not solve automatically, under the Task Name column. Once these tasks are completed manually by the SME, they can then select that Task from the queue and start teaching Bardioc™ how to re-create this solution in the future.
\nThe Start Teaching button in the Actions column is only available for Tasks that do not currently belong to anyone. Meaning they haven’t been assigned, and no other user has started a Teaching Session for that Task yet. Once a user clicks this button and begins teaching Bardioc™ their username will appear in the Owner column of that specific Task, and no-one else will be able to edit the Teaching Session.
\n\nOn the top left one can Filter the Tasks shown in the queue to find their own or their team’s Tasks. Or they can Search for a specific Task by name in the field on the top right.
\nOnce a user has started teaching Bardioc™ the Steps to automate a specific task, that Teaching Session belongs to them, and if they were to exit or Close the app while teaching, the button Continue Teaching will appear in the Actions column for that Task.
\n\nA Teaching Session will require listing the Steps it takes to solve a Task, and describing each one in detail. The number of Steps specified will appear on the bottom part of the first circle in the Progress column. The number above it represent how many of those Steps have been fully defined. After all Steps have been fully described, an SME will Hand Over the teaching session to a Knowledge Expert for the agile automation cycle to be complete.
\nAfter clicking the \"Start Teaching\" button on a specific Task, the user is directed to the Knowledge Acquisition Tool (KAT) where Bardioc™ Chatbot will ask questions about the Task and how the SME solved it manually. They can choose to give their Teaching Session a name on the top left, so it can be found easier in the future in the automation queue; and on the top right, they can find options such as archiving a conversation, closing the Teaching Session or the app, and here they can also find further details about the Tasklist app.
\nThe first thing the Bardioc™ Chatbot will ask in a new Teaching Session is to list the Steps they took. An SME would reply in the message input field at the bottom, and press Enter after each Step or click the Send button. After all the Steps have been specified the SME should type \"done\" in order to move onto the next part of teaching.
\n\nAt the top of the chat view a new tab will appear for each Step, where the user can describe each in more detail by having a \"Sub-Chat\" conversation with Bardioc™, whose questions become a bit more specific here. The main chat conversation takes place in the Description tab, and once the user has finished listing the Steps, they can choose to be redirected to a \"sub-chat\" either by clicking on the respective tab at the top, or by selecting the Step from the drop down list that Bardioc™ Chatbot provides, and pressing Go.
\n\nIn each \"sub-chat\" Bardioc™ will try and extract details about the Step that is being defined, and this is done in 4 parts. The first part asks the user to describe the Step in more detail. This description should contain as much information as possible, so that when another person might be offered the option of re-using this Step they can understand what it does and how by reading this description.
\nIn the second part of the \"sub-chat\", Bardioc™ tries to understand where this Step could be carried out so the knowledge could be applied. While answering this question, one needs to understand the environment like Bardioc™ does, and describe any conditions that it needs to meet, in order for this Step to be successfully completed.
\n\nEach Step needs to be described following the logical flow Where, When, What. How to think about answering the question \"Where\" is covered in 4.5. In part 3 of the chatbot questions, Bardioc™ tries to learn when the Step that’s being defined can be carried out.
\nIn this part, one needs to consider if there are any conditions that need to be fulfilled before this Step can be executed, and describe those conditions as clearly as possible. Information which Bardioc™ will use to check the conditions stated here, comes from the Automation Task. So, if the SME has a clear idea of the Task and can look into a Task to see its contents, they can use that information to state more clearly the conditions that need to be met before this Step can be run.
\nWhen answering, it’s best to separate the conditions by a semicolon \";\" and to list them all in the same line. The user must at this point provide any peculiarities of the Step, and be specific with possible values which would always need to be considered for this Step. As Bardioc™ will try to map the user input to Variables that it already knows, if the SME is aware that a certain condition refers to a known Variable, they can save some time from the Variable review by writing the Variable name directly.
\nSo far, a Step’s conditions for where and when it should be carried out have been defined. Now it’s time to describe the Step itself, so, the action that’s being taught to Bardioc™ and exactly how it was completed manually.
\nWhen replying to this chatbot question, one should always keep in mind that Bardioc™'s not just being taught what the SME did manually, but also how Bardioc™ can replicate this step. So, they should consider all the details that may be unknown to Bardioc™ until this point.
\nFrom the list below, not all the questions will fit for all Steps, but they should however be used as guidelines for this part:
\nWhat did I use to carry out this Step?
\nAre there any restrictions to this Step?
\nHow do I define success for this Step? Is it:
\ntrue/false?
\nspecific value?
\nrange of values?
\nWhat does this outcome tell me about my Step?
\nThe above will prove to be very useful to the Knowledge Expert who will review the code that Bardioc™ generates automatically from the chat. Once again, it’s important to cover everything for this reply in one line, so when necessary one should use \";\" or full stops to separate sections of a reply from one another.
\nAfter fully describing the final Step, the user is redirected back to the Description tab, where the Teaching Session originally began. Bardioc™ prompts the user to double check their input for completeness, and they are given the option to add more knowledge, request peer review, or hand over to Knowledge Expert. If the user confirms that the knowledge acquisition is complete, they can request a review from colleagues (please see chapter 2.2.) before finally handing this session over to a Knowledge Expert by clicking the \"Send to a Knowledge Expert\" button.
\n\nAfter a Handover, the user and other SMEs, can no longer edit this Teaching Session. Bardioc™ automatically generates Knowledge Items (KIs) out of the chat conversation, and it is then the job of the Knowledge Expert to review this knowledge and make sure it’s aligned with the user input.
\n\nA completed Teaching Session that has been handed over to an Knowledge Expert is now shown on the Tasklist as shown below.
\n\nThe details, such as date and owner, are shown below the Task Name upon clicking on it, and the session progress shows the Handover icon highlighted in blue. On the left of the icon one can see the number of Steps that were defined, and on the right of it, the number of KIs written for this Teaching Session. After Handover SMEs can only visit a Teaching Session as it’s no longer possible to edit.
\n![\"issue](\"/7.0/images/issue_state_diagram.png\")
The black lines indicate transitions done by the engine, whereas:
\nsome transitions can be triggered by special KI language commands
\nand some others will be triggered only be engine’s internal issue handling
\nThe red transitions can only be done from outside.
\nnew issue which is ready to be procesed by engine
\nFor compatibility reasons a missing status value is taken as 'NEW'
\nEngine is currently working on that issue
\nIssue processing was successfully finished. Technically that means: through application of KIs all to do variables have been deleted.
\nThis is a final state.
\nIssue processing was suspended to wait for some external event (e.g. user approval).\nAn issue in that state must be set back to PROCESSING from outside.
\nIssue processing was stopped. In most cases this status means engine ran out of applicable knowledge.
\nThis is a final state.
\nIssue processing was forcefully terminated. This could be triggered internally by some error conditions (see below) or externally (e.g. Connector/CLI).
\nThis is a final state.
\n| from state | \nto state | \ntrigger | \n
|---|---|---|
NEW | \nPROCESSING | \nsuccessful loading issue | \n
PROCESSING | \nRESOLVED | \nno todo variable in issue (anymore) | \n
PROCESSING | \nWAITING | \nKI command | \n
PROCESSING | \nSTOPPED | \nKI command | \n
PROCESSING/NEW | \nTERMINATED | \n\n
| \n
During issue processing, if it’s attributes size reaches limit of 1MB, it will automatically be terminated!
\n| \n\n | \n\n \n \nengine stores a status change reason into\n | \n
The transitions listed below are those that are compatible\nwith the intended issue lifecycle.
\n| from state | \nto state | \ntrigger | \n
|---|---|---|
PROCESSING | \nTERMINATED | \nexternal tool (e.g. connector) decides then engine should not process that issue anymore | \n
WAITING | \nTERMINATED | \nexternal tool (e.g. connector) decides then engine should not process that issue anymore | \n
PROCESSING | \nWAITING | \nexternal tool decides that engine should (temporarily) stop processing that issue | \n
WAITING | \nPROCESSING | \nexternal tool decides that a\n issue processing can now continue | \n
In many cases a STOPPED issue means that there was not sufficient knowledge to solve it.
\nThat’s why any issue being in status STOPPED is a candidate for a new knowledge acquisition session
\nThe KAT (knowledge acquisition tool) will (among other things)
\ndisplay STOPPED issues and their relation to existing knowledge acquisition sessions
\nallow to create new knowledge acquisition sessions and link them to one of those issues
\n
In contrast to Automation Issue Lifecycle\nthis section will (also) describe how engine will react on any status value/transition that is incompatible with the intended issue lifecycle.
\nThe engine will run the issue through the following check sequence:
\nensure data is present
\nensure issue is correctly tagged
\nensure history is loaded (setting deployment status to \"deployed\")
\noptionally check tenant and abort processing if not \"our\" tenant
\nperform state check
\ncheck for external resolve
\ncheck for waiting and do nothing in that case
\ncheck for delayed and reset to processing
\ncheck for undefined variables
\nset to processing and proceed to node check
\nperform node check
\nif no node info present, set deployment status and wait
\ncheck if processing node still exists, fallback to origin node
\nif access denied or origin and processing node are deleted, set to waiting
\nset deployed status and proceed to check_todos
\ncheck open ToDo variables
\nno \"ToDo\" variable: set status to RESOLVED
attributes to be checked
\nogit/Automation/processingNode
ogit/Automation/originNode
if processingNode is reported as \"deleted\", originNode will be used as a fallback\nif current processing node is reporting \"access denied\", issue will be set to TERMINATED
Possible error cases during node check:
\nto be verified if still valid for 0.14.x or higher
\n| problem with node-ref | \nexpected behavior of engine | \nremark | \n
|---|---|---|
no defined | \nogit/Automation/deployStatus set to 'waiting for node assignment' | \nonly available \"active waiting\" as clients may create issue and then supply data in second step | \n
no existing (404) | \nset to | \nwith error message in | \n
no access (403) | \nset to | \nwith error message in | \n
type is not in automation scope | \nignored | \nnode type where issue starts processing is not checked. | \n
| \ndecomissioned should be seen as \"deleted\" from engine | \n\n |
| \nnot implemented, yet | \nautomationState is currently not honored by engine | \n
Note: here we assume that the engine hasn’t worked on that issue before, i.e. /VNodeTag is not set, yet.
value of ogit/status upon issue creation | \nexpected engine behavior | \nremark | \n
|---|---|---|
not set | \nload and set to | \nunless some error conditions occurs | \n
| \nload and set to | \nunless some error conditions occurs | \n
| \nload but no status change | \nunless some error condition occurs | \n
| \ndo not load | \n\n |
| \ndo not load | \nlegacy status. superseded by | \n
| \ndo not load | \n\n |
| \ndo not load | \n\n |
| \nload and keep state | \nuntil status is changed externally | \n
illegal value | \ndo not load | \nunless there’s a valid | \n
Note: most transitions listed below are those that are incompatible\nwith the intended issue lifecycle. Nevertheless Bardioc Engine\nhas a define behavior for all corner cases.
\nAssumption: those changes are not done by the engine itself but engine is running (e.g. setting issue to RESOLVED while engine is not running will simply make engine ignore that issue on next reload)
current value of ogit/status | \nnew value of ogit/status | \nexpected engine behavior | \nremark | \n
|---|---|---|---|
| \n
| \ntreat like a new issue | \nnew | \n
| \n
| \nreload into engine as | \nnew | \n
| \nany other | \nignored by engine | \n\n |
| \n
| \nunload from engine | \nregular state transition | \n
| \n
| \nexcept state change | \nregular state transition | \n
| \n
| \nset back to | \n\n |
| \n
| \nunload from engine | \nregular state transition | \n
| \n
| \nexcept state change | \nregular state transition | \n
| \n
| \nset back to | \n\n |
ki\n name: \"TestKi\"\n version: \"0@NoName\"\n description: \"Just a simple test KI\"\non\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\nwhen\n VarA\n VarB[\"key\"] # match on key\n VarC[VarA] == NodeType\n list VarD\n VarF as Test\n MonitoringStatus@in == \"true\"\ndo\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 non-zero exit code\")\n else\n log(\"execute returned ${ExecuteOutput}\")\n endki\n name: \"TestKi\"\n version: \"0@NoName\"\n description: \"This KI will retry execution up to three times upon AH failure\"\non\n ogit/name == \"default_issue_node\"\n\nwhen\n ProcessIssue\n ticketId == \"IN-XXXXX\"\n ? counter < 3 := 0\n ogit/Automation/processingTimestamp\n\ndo\n #AH to the Solve ticket\n LOCAL::SYSTEMRC = \"1\"\n\n if LOCAL::SYSTEMRC == \"0\" then\n delete(ProcessIssue)\n else\n log.error(\"process ticket failed\")\n counter = counter + 1\n log(counter)\n endki\n name: \"TestKi\"\n version: \"0@NoName\"\n description: \"Update the ticket with a comment stored directly in the ToDo AddComment\"\non\n ogit/name == \"default_issue_node\"\n\nwhen\n AddComment\n ticketId\n valEnterpriseId\n\ndo\n\n # Call to update a Ticket in Valuemation with a ticket message\n body: LOCAL::BODY,\n code: LOCAL::CODE,\n headers: LOCAL::HEADERS,\n exit: LOCAL::ACTIONSYSTEMRC = action(capability: \"UpdateTicket\",\n mainDescription: \"ticket description\",\n ticketNo: \"${ticketId}\",\n descriptionBody: \"${AddComment}\",\n descriptionTitle: \"Updating ticket\",\n tenantId: \"${valEnterpriseId}\"\n )\n\n if LOCAL::CODE == \"200\" then\n delete(AddComment)\n else\n log(\"Updating ticket failed\")\n endki\n name: \"TestKi\"\n version: \"0@NoName\"\n description: \"KI to be trigger before the datagroup.de:Default:AutoStopIdleIssues KI, it will forward the ticket to the responsible support Group for manual resolution\"\n tier: \"fallback\"\non\n ogit/name == \"default_issue_node\"\n\nwhen\n ? ogit/Automation/maxIdleTime@any := 6\n ExecIdle > ogit/Automation/maxIdleTime\n ticketId\n assignmentGroup == \"Bardioc\"\n responsibleSupportGroup\n description\n\ndo\n\n body: LOCAL::BODY,\n code: LOCAL::CODE,\n headers: LOCAL::HEADERS,\n exit: LOCAL::ACTIONSYSTEMRC = action(capability: \"ForwardTicket\",\n ticketNo: \"${ticketId}\",\n supportGroup: \"${responsibleSupportGroup}\",\n description: \"${description}\"\n )\n\n # result interpretation\n if LOCAL::CODE == \"200\" then\n log(\"Forwarded to support group\")\n else\n log(\"Forward Ticket to support group failed\")\n endki\n name: \"TestKi\"\n version: \"0@NoName\"\n description: \"Before start any further steps you have to check if the first and last name contains special letter like ä,ö,ü or accent mark\\. If so you have to remove or correct it\"\n tier: \"fallback\"\non\n ogit/name == \"default_issue_node\"\n\nwhen\n CheckSpelling\n vorname\n\ndo\n\n exit: LOCAL::EXIT, result: LOCAL::vor = javascript('\n spechrs = { \"ä\" : \"ae\", \"ö\" : \"oe\", \"ü\" : \"ue\", \"ß\" : \"ss\",\n \"Ä\" : \"Ae\", \"Ö\" : \"Oe\", \"Ü\" : \"Ue\",\n \"á\" : \"a\", \"â\" : \"a\", \"Á\" : \"A\", \"Â\" : \"A\",\n \"é\" : \"e\", \"ê\" : \"e\", \"É\" : \"E\", \"Ê\" : \"E\",\n \"í\" : \"i\", \"î\" : \"i\", \"Í\" : \"I\", \"Î\" : \"I\",\n \"ó\" : \"o\", \"ô\" : \"o\", \"Ó\" : \"O\", \"Ô\" : \"O\",\n \"ú\" : \"u\", \"û\" : \"u\", \"Ú\" : \"U\", \"Û\" : \"U\",\n }\n str = \"${vorname}\"\n for(chr in spechrs)\n {\n str = str.replace(new RegExp(chr,\"g\"),spechrs[chr])\n }\n str\n')\n\n # result interpretation\n if LOCAL::EXIT == \"0\" then\n vorname = LOCAL::vor\n log(\"Name has been reviewed\")\n delete(CheckSpelling)\n else\n log(\"Failed to check Name spelling\")\n endki\n name: \"TestKi\"\n version: \"0@NoName\"\n description: \"example on how to manipulate dates\"\non\n ogit/name == \"default_issue_node\"\n\nwhen\n ProcessIssue\n\ndo\n\n # Displays current date into a given date format\n result: LOCAL::DATE = dateprint(format: \"%A, %Oe, %B, %Y %H:%M:%S\")\n log(\"Current date formatted as: Weekday, Day of the Month, Month, Year Time: ${LOCAL::DATE}\")\n\n # Converts date into timestamp\n LOCAL::DATE1 = \"2024-11-05T18:00\"\n result: LOCAL::DATEMS = javascript(\"\n let date = new Date(`${DATE1}`).getTime();\n date;\n \")\n log(\"Date as a timestamp: ${LOCAL::DATEMS}\")\n\n # Convert timestamp to a given date format\n result: date = dateprint(timestamp: LOCAL::DATEMS, format: \"%d.%m.%Y\")\n log(\"Date formatted as: Day.Month.Year ${date}\")ki\n name: \"TestKi\"\n version: \"0@NoName\"\n description: \"example on how to query the graph\"\non\n ogit/name == \"default_issue_node\"\n\nwhen\n GraphQuery == \"Graph Query 1\"\ndo\n # Graph Query\n # LOCAL::NODEID contains the list of found ogit/_id\n LOCAL::NODEID = \"\"\n exit: LOCAL::EXIT,\n output: LOCAL::OUTPUT = query('vertices', 'ogit\\/_type:ogit\\/MARS\\/Machine ',\n fields: \"ogit/_id\",\n each: begin\n LOCAL::NODEID = \"${ogit/_id}\"\n log(LOCAL::NODEID)\n end\n )\n\n # result interpretation\n if LOCAL::EXIT == \"0\" then\n delete(GraphQuery)\n else\n log(\"Failed to complete the query\")\n endVisit the whole guide about the approval AH here
\nPlease see a full example in here
\nKnowledge 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 \n \nMandatory elements for all KI are: | \n
Every Knowledge Item is build with these sections:
\n| Section | \nDescription | \n
|---|---|
| \nMeta information about the KI, like | \n
| \nSpecifies on which node the knowledge will be applied and which conditions should exist on the node | \n
| \nSpecifies which conditions should exist on the issue to execute the KI | \n
| \nCommands to execute in the case of issue binding | \n
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\")
KIs can be assigned to one of three priority tiers which will affect KI selection priority.
\ndefault | \nthe normal KI priority which should be used for almost all normal KIs | \n
policy | \nthe policy level will guarantee execution before KIs of the other tiers | \n
fallback | \nKIs in this tier will only ever be executed when not default or policy KIs are matching | \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.
\nIf 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.
\nImagine 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![\"Tiers\"](\"/7.0/images/ki-syntax/tiers.png\")
\nThe tier must be explicitly stated in the KI header; if left unspecified, the default value for the tier is used.
\n![\"Tier](\"/7.0/images/ki-syntax/TierHeader.png\")
\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
ki\n name: \"Tutorial test KI\"\n version: \"1@Author\"\n description: \"Tutorial test KI to describe KI Syntax 6.0\"\n tier: \"default\"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:
\non\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 endThis 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:
with <vertexType>@<edgeDirection>[:<edgeType>]\n <Conditions>\nendwhere <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\n ogit/_type == \"ogit/Person\"\n with ogit/Software/Application@out:ogit/uses\n ogit/name == \"LunchApp\"\n ogit/url\n endThat 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:
ogit/name attribute has value \"LunchApp\"
attribute ogit/url exists
The instructions defined in do will only be executed when all conditions\nof when section are matched.
when\n VarA\n VarB[\"key\"] # match on key\n VarC[VarA] == NodeType\n list VarD\n VarF as Test\n MonitoringStatus@any == \"true\"Once all conditions are matched the Knowledge Item will be applied. The\ndo section defines which actions are performed. It might look like this:
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 \n \nDesigning Knowledge Items with \n \nAs 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
You can use the If function to add logical branching to your Knowledge Item.
\ndo\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\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
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\nVarA #This is also a comment| \n\n | \n\nIf you wish to see how these sections are used you can refer to a full example.\n | \n
This guide contains all the essential information for Knowledge Experts to teach Bardioc™ how to automate knowledge described by SMEs most efficiently. It provides an overview of the Bardioc™ world, direction on how to interact with Bardioc™ for best results, and hints and tips on navigating the user interface.
\nBardioc™ is an automation tool based on artificial intelligence, created by Almato. It can be used to automate both IT and business processes, enabling companies to utilise time and resources effectively.
\nKnowledge is taught to Bardioc™ in small pieces that contain the context in which they can be used. Then, when a Task is assigned to Bardioc™, it will try to solve it by recombining all the knowledge it’s been previously-taught based on the Task context at each given point in time. This means that Bardioc™ doesn’t learn in strict workflows like, for example, scripts. Instead, it will create a workflow in real time as it evaluates the Task context and, based on that, decides on the Steps to take, on the fly.
\n\nBardioc™ integrates into your environment in order to receive Tasks, the same way that you do! For example, these may be in the form of ITSM Tickets that are assigned to you, or submitting of forms, even e-mails. Integration is the first step because these Tasks will now all be \"delegated\" to Bardioc™, and only when Bardioc™ can’t solve it, it will go to the Subject Matter Expert (SME).
\nA simple look at the process is as follows:
\nTicket/Task is assigned to SME
\nSME sees what Bardioc™ has already done and determines which steps are missing from the solution
\nSME solves the Ticket manually
\nThey locate the Ticket in Bardioc™ Tasklist and press Start Teaching (This is the same when a Knowledge Expert wishes to teach Bardioc™ directly)
\nSME explains all the steps they took to Bardioc™ Chatbot in natural human language and hands it over to Knowledge Experts
\nA Knowledge Expert selects chat from their Tasklist view and converts it to code that Bardioc™ understands7.
\nNext time Task occurs, Bardioc™ will use this knowledge to solve the Ticket autonomously
\n\nTeaching Bardioc™ is made simple with the help of a chatbot, which will guide the knowledge transfer by asking the SME questions regarding the Task solution. Once they complete and hand over the chat, it’s then available to all Knowledge Experts of the same team in the Tasklist app.
\n\nBardioc™ is always working in the background, whether that be carrying out tasks, or learning how to automate new ones. This can be seen in the two modes Bardioc™ works in:
\nBardioc™ solves tasks automatically by applying pre-existing knowledge.
\nBardioc™ gets taught new knowledge to automate new tasks in an agile manner.
\n\nPrimarily, Bardioc™ needs to understand the environment that it will automate in, including which tasks can occur there. These can both be extended as the scope grows, but to start off one should select an end to end process to automate, and define which tasks can occur there and their triggers.
\nTriggers will be defined for each problem type, and an Automation Task will be created in Bardioc™ every time a trigger is detected. In the Automatic Execution Mode, Bardioc™ tries to solve each task by applying existing knowledge that it will have been taught previously.
\nIf the knowledge present is not sufficient for a specific task, Bardioc™ will request to be taught new knowledge in the Agile Automation Mode, so that it can solve the task automatically the next time a similar trigger occurs.
\nAutomating with Bardioc™ entails indirectly collaborating with various team members that will each use Bardioc™ differently. For this purpose, Almato has created some User Roles to better separate responsibilities, processes for hand-over, and allow for the user interface and training content to be better catered to each role.
\nA Bardioc™ Developer is responsible for creating and configuring the Action Handlers and Connectors planned in the Solution Design phase. They are familiar with the source and target systems, and the available Bardioc™ APIs.
\nExperts who will teach Bardioc™ how to automate processes they are knowledgeable on through a chat conversation where they answer some questions regarding said processes and tasks within them.
\nThis role will be given to users who understand how Bardioc™ works, and can edit Bardioc™'s automatically generated code to ensure it has translated content from an SME’s chat conversation correctly into KIs.
\nThis role will be given to users who understand how Bardioc™ works, permissions required for each user, and how to configure this using Bardioc™ User Interface.
\nOnce a business process has been selected for automation, a Business Analyst will design the automated solution for the tasks within that business process and how they will be transferred into Bardioc™. They will also define which external systems need to be connected to Bardioc™ and what content is needed from each.
\nThese designs will be communicated to a Developer who will create the necessary Connectors and Action Handlers which will import data into Bardioc™ for automation, and define how Bardioc™ interacts with external systems.
\n![\"MotW](\"/7.0/images/MotW_full.png\")
\nOnce the integration phase is complete, the Connectors will pick up any triggers that were defined to start an automation task, and push this information into Bardioc™. Bardioc™ then tries to solve said task with existing knowledge. If there is no knowledge applicable to the task at hand, the Connector should pick up on this, and inform the relevant Subject Matter Expert, who will complete the task manually.
\nAfter manual resolution, this knowledge needs to be taught to Bardioc™ for next time the same issue occurs. In this case, the automation task that was not able to be solved by Bardioc™ appears in the user interface listed in the Tasklist app. This is where the SME would need to locate it and start teaching the Bardioc™ Chatbot when they’re redirected to the Knowledge Acquisition Tool.
\nThrough the chat conversation, Bardioc™ understands the steps and translates it into code that is used for automation. These steps are called Knowledge Items and for the process to be complete, a Knowledge Expert would need to peer review Bardioc™'s translation and edit where needed, before deploying all the new knowledge so that Bardioc™ can solve the problem itself next time it occurs.
\nThis User Guide will look at the workflow only from a Knowledge Expert’s perspective.
\nWhen Bardioc™ can’t solve a Task, it means there’s missing knowledge. In this case, the Task will be handed over to a Subject Matter Expert (SME) and they will solve it manually. Lastly, the SME will teach Bardioc™ how to solve Tasks like this in the future. The way they do that is by talking to a chatbot and answering questions to further define the knowledge being transferred.
\nSMEs will teach Bardioc™ what they did in so called Steps. Each Step will be translated by Bardioc™ into Knowledge Items(KIs), which is what Bardioc™ uses to carry out actions and automate solutions. These KIs are generated based on the SME’s input, and Bardioc™'s understanding of it. Throughout the chat, Bardioc™ does check in with the SME on whether it understood correctly or not, but sometimes it requires a little extra teaching from a Knowledge Expert.
\n\nThis means that a Knowledge Expert should know how to create KIs as they’re, in essence, peer reviewing Bardioc™'s translation of natural language. By answering chatbot questions, the SME should have provided all the details necessary for a Step to be carried out, such as where it can be applied, under what conditions, and exactly how to carry out the action itself. This information can be mapped to the 3 parts of a Knowledge Item: On, When, Do.
\n![\"KE](\"/7.0/images/ke-ug/Bardioc7/KE_06.png\")
\nIt’s the Knowledge Expert’s job to verify that Bardioc™'s automatically generated code, does what the SME has described in the chat. Once this is done for each Step, the Knowledge Expert can request reviews from their colleagues to confirm the correctness of the new KIs. Then, they can be deployed into Bardioc™, and the next time this Task needs to be carried out, Bardioc™ can take care of it automatically.
\nOnce a Teaching Session is complete a Knowledge Expert can request a peer review from another colleague as a way of confirming their conversion, that all details are included, and that best practice is followed. Reviewers can be added by clicking on the icon at the top right of the screen in KAT, and typing in the names of the colleagues who will review and press OK.
\n\nThen, the Reviewer is notified, and their comments will be visible in the screen on the right, and the Teaching Session owner can choose to reply to the reviewer comments, make the suggested changes and resolve the comments, filter, sort,edit, delete etc.
\n![\"KE](\"/7.0/images/ke-ug/Bardioc7/KE_02.png\")
\nWhen a user replies to a comment, they have the option of tagging someone by using the \"@\" symbol and then their name. This will show up to the person who was tagged as a notification and a comment pending reply. When the owner of a session changes something that a comment by the reviewer is referring to, that comment is then marked as \"outdated\" and can be filtered out by clicking the icon at the top right, and unchecking the box. Here one can also sort the comments in the order they prefer.
\n![\"KE](\"/7.0/images/ke-ug/Bardioc7/KE_04.png\")
\nWhen a Teaching Session has been assigned to a Knowledge Expert to review, they will receive a notification by Bardioc™, and it will appear on their Bardioc™ Dashboard. First the number will change at the \"Tasks to be Reviewed\" counter, and the Teaching Session will also be available at the top of their Task List. Once they click to start, they’re taken to KAT, in \"Review Mode\". This can be seen at the top right, next to the Teaching Session name, there will be a title \"Review Mode\", and also the colour scheme is different to that of SME view and Knowledge Expert view.
\n![\"KE](\"/7.0/images/ke-ug/Bardioc7/KE_03.png\")
\nThis KAT also has a comments pane on the right hand side of the screen. Here, a reviewer can add general comments about the Teaching Session. They can also add comments by clicking on the speech bubble icon wherever available (please see list below) if they wish to be more specific about their review point.
\nA Reviewer can comment on:
\nThe Teaching Session as a whole
\nA specific Step
\nA specific KI
\nSpecific lines of KI code
\n\nWhen there’s multiple reviewers, one can distinguish who they’re referring to by tagging someone in a comment. This can be done simply using the \"@\" symbol and then their name. This will show up to the person who was tagged as a notification and a comment pending reply.
\nThere are two sides to reviewing a Teaching Session. The first is confirming that the expert knowledge that is being taught to Bardioc™ is converted correctly and is complete. The second is, ensuring that best practice is followed everywhere. This can be done with the help of checklists and best practice which can be gained through training and experience.
\nWhen the owner of a session changes something that a comment by the reviewer is referring to, that comment is then marked as \"outdated\" and can be filtered out by clicking the icon at the top right, and unchecking the box. Here one can also sort the comments in the order they prefer.
\nThe user interface for Bardioc™ is called Bardioc™ Dashboard and it contains information regarding the relevant Bardioc™ instance such as the Tasks that are still open and need teaching or converting and Tasks that the user has left incomplete. On the top right it shows the statistics about the instance such as the automation rate, and the number of tasks that the user has automated, along with the number of Knowledge Items created. In the view on the bottom right a user can have a closer look at their knowledge Items filtered by mode - validation, undeployed, or live.
\n![\"Dashboard\"](\"/7.0/images/ke-ug/Bardioc7/KE_14.png\")
\nFrom here we also get access to different apps which allow a user to interact with Bardioc™ and automate their tasks. There are 3 types of user roles one can have in Desktop, based on how they are expected to teach the tool:
\nSMEs: who will teach Bardioc™ how to automate their tasks using a chatbot
\nKnowledge Expert: who will peer review Bardioc™ automatically generated code, which is based on SME chat conversations
\nAdmin: who will configure Bardioc™ instances to match all member requirements, permissions and password resets.
\nso it’s best to check that the right permissions have been granted before continuing. This can be done by clicking on the Profile icon on the top right, and seeing the User Role in the View Profile section, as shown below.
\nThe Tasklist is a \"ToDo list\" for both SMEs and Knowledge Experts. Depending on the role, different filters and views are available. Start Teaching, Start Conversion, View Teaching take the user to the Knowledge Acquisition Tool where they can teach Bardioc™ the steps needed to resolve an Automation Task.
\n![\"KE](\"/7.0/images/ke-ug/Bardioc7/KE_07.png\")
\nKnowledge Experts can find all sessions that have been handed over by SMEs in their own ToDo List. Knowledge Experts can also view conversion tasks created by their colleagues, and can start a teaching just like the SME would do. These teaching sessions, however, are considered handed over and start with the Structure View in KAT.
\nKnowledge Expert Filters
\nThe filters in the Tasklist are shown all by default. The meaning for each can be found below.
\nMy Conversion Tasks:
\nTeaching Session handed over by SMEs and that the Knowledge Expert themselves has already began converting.
My Knowledge Tasks:
\nTeaching Session that have not had any SME input, but the Knowledge Expert has taken over to teach Bardioc™ the steps directly using KIs.
My Teams Tasks:
\nFiltered by users in the same organisation
Archived Tasks:
\nListing all archived tasks. (Archiving can be done using the 3 dots at the end of a row. Once archived they can be restored.)
My Review Tasks:
\nAll of the Tasks that the Knowledge Expert has requested peer review for.
My New Review Tasks:
\nAll of the Tasks that peers have assigned to the Knowledge Expert for review and they have note yet begun.
New Conversion Tasks:
\nTeaching Session handed over by SMEs
New Knowledge Tasks:
\nKnowledge Experts can also start a teaching session, here is where they’ll be able to see Teaching Sessions not started by an SME. In these Teaching Sessions, however, the Knowledge Expert is taken straight to structure / code view and the session is considered handed over.
The Knowledge Acquisition Tool is how knowledge gets inserted into Bardioc™. The SME will do this by talking to a chatbot, so their KAT user interface looks different to that of an Knowledge Expert’s. The steps described by the SME during the chat conversation will be visible in KAT, in the Chat View where the Knowledge Expert has read rights.
\n\nThey can edit Steps in the Structure View, and it’s recommended that this is done in natural language. From there, the Knowledge Expert can choose to browse through existing knowledge in case the SME’s description matches that of a pre-existing KI and can be reused, or they can have Bardioc™ automatically generate a new KI based on the chat conversation and this way grow their knowledge pool.
\nThis KI will appear in the Code View and the code itself can then be edited there. From here onwards, an Knowledge Expert must review Variables used, conditions, and the action a KI should carry out. Once this is complete, they can deploy the Knowledge Item, and Bardioc™ will then be able to solve tasks like this automatically in the future.
\n\nWhen generating a new KI, Bardioc™ tries to map content from the natural language to existing variables, which is the \"vocabulary\" Bardioc™ uses. The Knowledge Expert can edit this mapping or even create new ones. The logic behind the mapping suggestions is indicated on the screen in the form of coloured, straight and dotted underlining of the words the SME used to describe a step. Each indicator is explained below:
\n![\"KE](\"/7.0/images/ke-ug/Bardioc7/KE_08.png\")
\nDotted line
\nBardioc™ was able to match to an existing variable
Red line
\nBardioc™ wasn’t able to understand the user input
Blue line
\nBardioc™s suggestion was overwritten by the user or a new definition was added
KIM allows users to browse all knowledge that has been created within their environment. A Knowledge Expert can filter for deployed (available to the engine), KIs in \"Validation mode\", undeployed, or incomplete KIs. From here, a user can select a KI and then go to the teaching session where that specific KI was created in KAT.
\n![\"KE](\"/7.0/images/ke-ug/Bardioc7/KE_12.png\")
\nThe KI statuses are shown at the end of each line with corresponding icons.
\nGreen tick in a circle
\nKI is available to the engine for use.
Empty circle
\nKI is not available to the engine for use. It is currently \"Undeployed\" so it will not be considered during automation.
Chemistry icon (beaker)
\nKI is in \"Validation Mode\". This means that the Knowledge Item will be considered during automation, but will not actually be applied. Instead, while a KI is in this mode, Bardioc™ will log all the times that a Task matched the conditions of this KI, meaning (had it been Live) it would have been triggered when this Task occured. The details of the Validation statistics can be seen in more detail below.
Red warning sign
\nKI is syntaxtually incorrect.
\nBy clicking on a KI in the list one can get a closer look at the KI, its statistics, they can edit it, or change the KIs state all from the view in the right hand side. The first view shows the KI code and offers 2 buttons. The \"View in Knowledge Acquisition Tool\" button will take the user to the Teaching Session in which this particular version of the KI was created. If this Teaching Session belongs to them, they can also edit the KI contents.
\nThe second button is a dropdown list with KI states. If the user owns the KI, they can choose to change its state by deploying to \"Live\", \"Validation Mode\", or undeploying altogether.
\n![\"KE](\"/7.0/images/ke-ug/Bardioc7/KE_16.png\")
\nValidation Mode is a state in which the KI is considered during automation but not applied. So, all Tasks that come in will also check if this particular KI can be applied. But it won’t actually get triggered, so the KI won’t run any actions while in this mode, it will simply log all the times that it could have run. This is useful for validating that the KI’s conditions are correct. The engine stores all the logs of when this KI would have run on a Task in the second tab of the right hand view - the \"Validation Statistics\" tab.
\nIn the \"Validation Statistics\" tab a user can see all the times that a Task occured which would have triggered the specific KI, had it been in \"Live\" mode. One can select the range they wish to see from the statistics (last 24 hours, 3 days, months etc.) and here is also where they are shown the Tasks and given the option to have a closer look at each Task for further inspection by opening it in \"Task Inspector\" (please see following section)
\n![\"KE](\"/7.0/images/ke-ug/Bardioc7/KE_17.png\")
\nSimilarly, this view also offers a tab with \"Live Statistics\", which allows the user to see all of the Tasks that a KI has run on. They can also have a closer look at the Task history and view at which point exactly the KI was applied by opening the Task in Task Inspector. Lastly, the top right corner of a KI shows the KI versions. During the creation and editing of KIs, new versions are saved and are then accessible through KAT.
\n![\"KE](\"/7.0/images/ke-ug/Bardioc7/KE_15.png\")
\nThe Task Inspector is where a Knowledge Expert can have a closer look at what Tasks have entered into Bardioc™, their status, and which steps (KIs) they have triggered.
\n![\"KE](\"/7.0/images/ke-ug/Bardioc7/KE_09.png\")
\nAfter selecting a Task from the list, one can see which steps were taken and when, the findings of executed KIs, the changes that KIs made to the Task and, and where exactly in the environment those steps were taken.
\n![\"KE](\"/7.0/images/ke-ug/Bardioc7/KE_11.png\")
\nFor each Task, the Task Timeline will show the full list of KIs applied, and the environment Nodes they were applied in. After clicking on a KI on that list, one can find more details in the following views:
\nTask Content Display
\nHere one can find the contents of the Task at the point in time where the KI was applied. The Task is in JSON format, and the highlighting allows us to see which Variables were deleted (red), or added (green). If a Variable was updated, the original value will appear in red - as it’s being deleted, and the new value will appear in a different line in green.
Knowledge Item
\nThe code view of the Knowledge Item that was selected from the Task Timeline, can be found in the Knowledge Item view. From here, one can have a closer look into the KI’s conditions to understand why it was triggered, and get a better view of what it was designed to do. From here, one can also have a closer look into the KI by going to the Knowledge Item Management tool (KIM).
Current Node
\nThe Task will originate on a certain environment Node, and knowledge will be applied to it there, if that knowledge is not sufficient to resolve said task, the Task will traverse the Graph moving from one Node to another until it finds the knowledge needed. Here one can look into the contents of the Node (in JSON format) that the Task was in at the selected point in time.
Engine Log
\nHere’s where one can see the output of Bardioc™ implicit and explicit logging abilities. It’s useful when one is troubleshooting the outcome of a certain step, or simply see their log messages at that point in time.
(Task Content Display is available by default, the rest will need to be explicitly selected and de-selected from the dropdown list on the top right hand side.)
\n![\"KE](\"/7.0/images/ke-ug/Bardioc7/KE_10.png\")
\nThe Graph Explorer is a browser-base application desined to visualize and interact with data stored in a graph database. It allows users to explore entities(Nodes) and their relationships, view raw data and filter or query specific elements within the graph for better understanding and analysis.
\nTo start using the Graph Explorer, follow this link and use same credentials as for Bardioc desktop.
\nAs a KI writer, understanding the implemented model for your automation cases is essential, as you’ll need to reference specific Nodes within your KIs (ON block).
\nExploring Nodes and Attributes
\nFor example, to automate a task on a Windows machine, we create a Node of the type \"Machine\" with the specific value \"Windows\" within the Graph. Now, let´s explore how to locate this Node.
\nSelecting a Node Type
\nUse the filter in Graph Explorer to select the type of Node you want to view. Example: Select MARS/Machine and click Apply.
\nThe selected Nodes and their properties will appear on the left-hand side.
\n![\"SelectNode\"](\"/7.0/images/ke-ug/Bardioc7/SelectNode.png\")
\nNode Properties (Attributes)
\nNodes in the Graph are described by their properties (attributes), which fall into three categories:
Mandatory: Required attributes for the Node.
\nExample: ogit/MARS/Machine/class.
Optional: Attributes that add detail but aren’t required.
\nExample: ogit/Automation/automationState.
Free: Custom attributes that you can create to describe your entity if predefined attributes are insufficient.
\nExample: /ExpenseReport (these do not start with ogit/, as they are customer-specific).
Note: Attributes starting with \"ogit/_\" are automatically generated by Bardioc™ when a Node is created.
\nExample: \"ogit/_modified-on\": \"Tue, 03 Sep 2024 09:33:11 GMT\" , \"ogit/_graphtype\" : \"vertex\"
![\"FreeAttribute\"](\"/7.0/images/ke-ug/Bardioc7/FreeAttribute.png\")
\nKey concepts to learn
\nOntology: A formal description of knowledge within a domain, including its elements and relationships.
\nGraph Database: Built on a subset of the Ontology, it contains attributes were values tailored to the specific automation case we want to work on.
\nGraph Explorer: A powerful tool for visualizing and exploring data within the Graph Database.
\nFor a full guide on how to query the graph, please check this link
\nGraph Explorer App in Bardioc Desktop
\nA limited version of this tool is also accessible from the main Bardioc dashboard. The Graph Explorer App allows you to explore Nodes within your Bardioc instance.
\n![\"GraphExplorerApp\"](\"/7.0/images/ke-ug/Bardioc7/GraphExplorerApp.png\")
\nKey Features:
\nFinding Nodes:
\nSearch for Nodes by type, scope, or organization, or use the search box to locate a specific Node.
\nAccess Node Data:
\nSelect a Node to access its data.
\nClick \"Show OGIT Values\" on the right-hand side to view all metadata for the selected Node.
\n![\"MainPanel\"](\"/7.0/images/ke-ug/Bardioc7/MainPanel.png\")
\nGraph View:
\nSelect \"Graph View\" to visualize relationships between the selected Node and others in the graph.
\n![\"GraphView\"](\"/7.0/images/ke-ug/Bardioc7/GraphView.png\")
\nCustomizing the Panel View:
\nUse the \"Save\" icon on the left-hand side module to customize and save the panel view.
\n![\"SaveIcon\"](\"/7.0/images/ke-ug/Bardioc7/SaveIcon.png\")
\n![\"SavePanel\"](\"/7.0/images/ke-ug/Bardioc7/SavePanel.png\")
\nThese customizations are easily accessible via the three-dots icon on the left-hand side.
\n![\"AllPanels\"](\"/7.0/images/ke-ug/Bardioc7/AllPanels.png\")
\nWhy Use the Graph Explorer App?
\nThis app is invaluable for checking existing Nodes in your instance. For KI writers, it helps identify the variables you need to use in the ON block, ensuring your KIs are properly bounded and effective.
Bardioc™ Chatbot aims to extract information from an SME regarding the steps to automate a certain task that it was not able to automate before. Which means that, ideally, each teaching session will begin with a Task that has been \"stopped\" and was not automatically resolvable by Bardioc™.
\nFrom each step Bardioc™ is trying to learn where it can apply this knowledge (in the case that there’s environment data present which limits its application), and when it can be applied, meaning what information does the task definition need to contain for this step to be carried out. Lastly, Bardioc™ tries to extract exactly what action is to be taken and how it can recreate that specific step when the time comes.
\nThe replies the SME will give to these questions, will show up for the Knowledge Expert in the Structure view of a Teaching Session in KAT. The replies will respective fill the on, when and do section of a KI. So, it’s important for the Knowledge Expert to have in mind that descriptions provided in the on block, will determine which of the Environmental Nodes this KI is applied to. Similarly, the answers for the when block, will determine what information from the Task is needed for this KI to trigger, and the do block will show what exactly needs to be done.
\n![\"On](\"/7.0/images/aie-ug/On_When_Do.png\")
\nWhile describing the steps, Bardioc™ tries to map natural language to vocabulary it recognises, which consists of Variables. This mapping can be seen by the colour-coded underlining of words.
\n\nThe logic behind the mapping suggestions is indicated on the screen in the form of coloured, straight and dotted underlining of the words the SME used to describe a step. Each indicator is explained below:
\nDotted line
\nBardioc™ was able to match to an existing variable
Red line
\nBardioc™ wasn’t able to understand the user input
Blue line
\nBardioc™s suggestion was overwritten by the user or a new definition was added
A Knowledge Expert needs to confirm Bardioc™'s mapping when autogenerating KIs. This can be done by clicking on underlined words and selecting an existing variable from the pre-defined list, or creating a new one by defining the variable name, a description, and an indicator if it should serve as a ToDo variable or not.
\nA ToDo Variable differs from other [\"Information\"] Variables as it implies an action needs to be taken. For example, ApproveOrder is an action that needs to be taken, whereas OrderApproved provides information of the status. The main function of the ToDo Variables is to indicate to Bardioc™ that something is to be done. Once the necessary steps are taken to complete an action indicated in a ToDo Variable, that Variable is then deleted. Bardioc™ will continue to process Tasks (\"PROCESSING\" state) for as long as there are ToDo Variables still present.
\nWhen all ToDos have been deleted the Task state changes to \"RESOLVED\" meaning that it has been solved fully autonomously by Bardioc™. If the existing knowledge inside Bardioc™ at a given point in time is not sufficient to carry out all necessary steps, so there are ToDo variables still left on the Task but no KI is triggering, the Task will stay in PROCESSING state. When a Task is in PROCESSING but no knowledge is being applied, Bardioc™ will wait until the Task has been idle for 900 seconds, then will automatically change its state to \"STOPPED\" indicating that Bardioc™ could not solve the Task autonomously and will need to be taught the missing knowledge after an SME successfully completes it manually.
\nAs Variables are global, and KIs are eligible to be applied to any Task, it’s good to agree on a set of rules regarding Variable and KI naming conventions. The suggested best practice can be found below:
\nToDo Variables always start with a verb.
\nInformation Variables always start with a noun.
\nCamelCase is used for Variable names (to differentiate between the two at a glance, ToDos can start with a capital letter, and information variables with lowercase).
\nVariable description should contain what the variable indicates, expected values (e.g. Variable indicates the current free memory available on a server. Expected values are in GB), and a short description on keys usage, when applicable.
\nKI Title should be consistent with its contents (double-check this at the end if forking, or copy-paste is used).
\nKI Description should summarize Applicability, Situation and Action in one or two sentences.
\nWhen a newly-handed-over Teaching Session begins, the Knowledge Expert, should go through it briefly, to get a view of what is being automated. Then, they would work on each Step one by one, to maximise Bardioc™'s efficiency.
\n![\"Step](\"/7.0/images/aie-ug/Step_Description.png\")
\nThey should ensure the Step definition is clear as they will need to browse through existing knowledge that Bardioc™ has found to be eligible for reuse, or trigger the automatic code generation to create a new KI. The following principles were created to aid in this process, and to refer back to while teaching Bardioc™.
\n![\"Automatic](\"/7.0/images/aie-ug/Automatic_Code.png\")
\nVariable declaration needs to be completed (wherever the SME has skipped this step)
\nNo variables used for substitution in DO block without having checked for them in ON or WHEN block (This will also break the colour-coding) not entirely sure this was just for Substitution, for example, it didn’t like ogit/Schedule/Calendar == something either
\nTry to understand KI description as a whole (logically, what is the SME trying to teach Bardioc™ to do? Have a clear answer for this, and don’t let the Variable suggestions sway you)
\nWhen there are suggested KI, always inspect those first to see if 1 could be reused for this same purpose
\nOnly if none can be reused, create a new KI
\n![\"KE](\"/7.0/images/ke-ug/Bardioc7/KE_13.png\")
\nBardioc™ automates using Knowledge Items (KIs), which are atomic representations of Steps that are taught to Bardioc™ by an SME. Once added to the pool, KIs can be re-combined with existing knowledge inside Bardioc™ to form automated solutions of similar Tasks. The SME input will be given through a chat conversation with Bardioc™ Chatbot, and Bardioc™ then can convert this knowledge into KIs.
\nAn Knowledge Expert will review SME input, and ensure that Bardioc™'s given the right amount of detail and context in order to get the best results from its automatic code generation feature.
\nThe SME will sometimes use words that are not yet in Bardioc™'s Vocabulary, in which case they can extend this by defining a new Variable. If an SME skips Variable definition, or matching of existing Variables, it falls on the Knowledge Expert to map the natural language to Variables using the context provided in the chat. Once all the necessary Variables are defined, Bardioc™ has a basis for the conversion.
\nKnowledge Items contain information on where and when they can be applied. In practice, this means each KI contains conditions that need to be met by the Environment, and others that should be met by the Task. Bardioc™ begins automation with a pre-existing environment, in the form of a graph.
\nThis graph will typically contain representations of factual knowledge which are relevant to the field of automation. Single instances of these representations are called Nodes. This information is inserted into Bardioc™ at the time of Integration, and it is a form of enabling Bardioc™ to understand the context in which it’s being taught, and providing it with the means of running actions on said Nodes.
\nEach Node describes a part of the environment using Variables, which is Bardioc™'s existing Vocabulary. These Variables can be read by a Knowledge Item, which is what happens at the time that a new KI is inserted into Bardioc™. The ON block of a KI will contain conditions which the Variables of existing Nodes need to match. For each match, the Knowledge Item is made available for use, on that Node. What this means is that Knowledge \"sits\" on Environment Nodes, and is idle until a Task occurs.
\nTasks are a list of attributes that describe the situation at a given point in time. Tasks will always originate on an Environment Node, indicating that a certain task or process, likely affecting that Node, needs to be carried out. As soon as a Task is created, Bardioc™ will check all of the KIs available on the Node it originated on, and will trigger the one(s) whose WHEN conditions are met by the specific Tasks.
\nKI Syntax is a formalization language for knowledge around automating processes. It is the basis for the Knowledge Items (KI).
\nThe assumption is, the system will have access to the same information as any (privileged) user and needs to be taught how to interact with the data in order to solve Tasks. KI Syntax 6.0 describes logic that processes/gathers/generates data in a certain way to contribute to the overall problem solution. This logic is stored in the Knowledge Items. Bardioc™ Engine applies Knowledge Items to its tasks.
\nApplication of Knowledge Items works by matching data to KIs that call for these conditions and associating each KI to these data points. This is called \"binding\". At any time many Knowledge Items can be \"bound\" to the same data.
\nA Task includes the current state of data gathered/generated for this Task and the history of steps and changes made to the data during processing.
\nA very simplified Task could look something like this:
\n{\n \"/Subject\": \"MyTestTask\",\n \"/MyVariable\": [\"FirstValue\", \"SecondValue\"]\n \"ogit/Automation/originNode\": \"pzcxyhawulkadasnwascxzy\"\n}While KI Syntax 6.0 borrows heavily from common programming language features like string expansion or comparison operators, it should not be confused with a programming language. KI Syntax 6.0 purposefully does not natively support creation of large monolithic algorithms. The goal is to write atomised bits of knowledge that can be freely strung together by their inputs and outputs and are as re-usable for as many use cases as possible.
\nThe core information is grouped in the Functions and Definitions parts. The Definitions section contains information on concepts such as aliases, scoping, data values etc. The most important section here is the “Matching variables and values”, where we see all the syntax necessary for variable matching. This is how a KI would communicate criteria, which means these are only used in the ON or WHEN blocks of Knowledge Items.
\nThe Functions dropdown contains information on how Bardioc can carry out actions on target systems. This will be information primarily used in the DO section of a KI. Functions require arguments which are either unnamed ordered (positional) or named (keyword), depending on the function.
\n![\"FunctionsArguments\"](\"/7.0/images/ke-ug/Bardioc7/FunctionsArguments.png\")
\n
\nThe function results are returned as tagged values, and matched to variables using the syntax:
<tag>: <var>,\n<tag2>: <var2> [...] = function(...)The full list of implemented functions can be found in KI Syntax.
\n\"Data in Bardioc is stored as lists of values“. Essentially, every variable in Bardioc is a list.
\nLists are a number of items.\nDuring automation Bardioc can only see one value at a time from the list and it is very important to mention that there is no order in lists, meaning that the value a KI \"sees“ when triggered is random.\nWhen lists have only one single value, they are refered as variables, concept that we have previously explained.
\nDefinition is done using square brackets, and elements in quotes.
\nDeleteFilesOn = [\"ServerA\" , \"ServerB\", \"ServerC\"]
ki\n name: \"KI 1\"\n version: \"0@NoName\"\n description: \"handling list\"\n\non\n ogit/name == \"default_issue_node\"\n\nwhen\n DeleteFilesOn\n\ndo\n log(\"Here is what the KI sees as Value of DeleteFilesOn variable ${DeleteFilesOn}\")\n delete(DeleteFilesOn)ki\n name: \"KI 2\"\n version: \"0@NoName\"\n description: \"handling list\"\n\non\n ogit/name == \"default_issue_node\"\n\nwhen\n list DeleteFilesOn\n\ndo\n log(\"Here is what the KI sees as Value of DeleteFilesOn variable ${DeleteFilesOn}\")\n delete(DeleteFilesOn)Let´s observe what will happen when these two KIs get triggered.\n
Task Inspector for KI \"Handle Lists 1\":
\n![\"TaskInspectorKI1_A.png\"](\"/7.0/images/ki-syntax/TaskInspectorKI1_A.png\")
\n![\"TaskInspectorKI1_B.png\"](\"/7.0/images/ki-syntax/TaskInspectorKI1_B.png\")
\n![\"TaskInspectorKI1_C.png\"](\"/7.0/images/ki-syntax/TaskInspectorKI1_C.png\")
\nTask Inspector for KI \"Handle Lists 2\":
\n![\"TaskInspectorKI2_A.png\"](\"/7.0/images/ki-syntax/TaskInspectorKI2_A.png\")
\n| \n | KI 1 (DeleteFilesOn) | \nKI 2 (list DeleteFilesOn) | \n
How many times this KI will run? | \n3 | \n1 | \n
What does this KI see as a value for DeleteFilesOn? | \n1st- “ServerA“ | \n[\"ServerA\" , \"ServerB\", \"ServerC\"] | \n
Therefore, we can work with a value from a list, or with the complete list.
\nIt is now clear from the example that if we want to match against a list, we need to use the prefix “list“ before the list name.\nIf we need to check against one value within a list, then do as follows :
\nDeleteFilesOn == \"ServerA\"
![\"MatchingList1.png\"](\"/7.0/images/ki-syntax/MatchingList1.png\")
\nYou can also check one value from the list, using the list variable and checking that this contains a specific value: “ServerA“ . The only difference here is that the variable now is the full list of values and not only a single value.
\nIn this case we use:
\nList DeleteFilesOn has “ServerA“
![\"MatchingList2.png\"](\"/7.0/images/ki-syntax/MatchingList2.png\")
\nThese conditions will not trigger the KI:
\nwhen\n DeleteFilesOn == \"ServerA\"\n DeleteFilesOn == \"ServerB\"But this condition will:
\nwhen\n list DeleteFilesOn has [\"ServerA\", \"ServerB\"]This is because the variable DeleteFilesOn on the first example can not have more than one value, while the list can contain several values.
\nMatch a list with subset form another list.
\nYou can either use the lists directly, or create aliases to refer to one list and check its content against another list
\nUsing the list directly:
\nwhen\n list serverToDelete\n list serverList has serverToDelete\n\ndo\n log(\"List of servers to delete ${serverToDelete}\")\n log(\"Alias ToBeDeleted: ${ToBeDeleted}\")\n log(\"Full list of servers ${serverList}\")Creating aliases for one of the list:
\nwhen\n list serverToDelete as ToBeDeleted\n list serverList has ToBeDeteted\n\ndo\n log(\"List of servers to delete ${serverToDelete}\")\n log(\"Alias ToBeDeleted: ${ToBeDeleted}\")\n log(\"Full list of servers ${serverList}\")The count function works for lists, and can determine the number of elements in a list.
\nlist serverList = [\"A\", \"B\", \"C\", \"A\", \"C\", \"D\", \"A\", \"E\"]
when\n ProcessIssue\n list serverList\n\ndo\n count(serverList)In this case, count will return ´8´.
\n| \n\n | \n\nWhat would happen if you delete \"list\" in front of the serverList?\n | \n
when\n ProcessIssue\n serverList\n\ndo\n count(serverList)If you omit \"list\" before serverList, the matching will only represent a single value in the DO block. Keep \"list serverList\" in the WHEN block to use all its respective values in the DO block.\nThis will result in :
\nseverList = \"A\" ;count = 1
You might want to count the ocurrences of a specific value within a list.
\nwhen\n ProcessIssue\n list serverList == \"A\"\n\ndo\n count(serverList)Now, the count will result in 3. In this case, the list serverList will remain as:
\n[\"A\", \"A\", \"A\"]
for the rest of the task. The matching process narrows down the available values in serverList.
\nIf you want to preserve the original content of the list, you should use an alias. An alias essentially becomes a separate variable list, allowing the original list to remain fully accessible.
\nwhen\n ProcessIssue\n list serverList\n list serverList == \"A\" as AServers\n\ndo\n count(serverList)\n count(AServers)You need to match both the list and the alias in te WHEN block to access both contents in the DO block. This way:
\nserverList = [\"A\",\"B\",\"C\",\"A\",\"C\",\"D\",\"A\",\"E\"] -→ count = 8
AServers = [\"A\",\"A\",\"A\"] -→ count = 3
If you only use the list “serverList“ with the alias:
\nwhen\n ProcessIssue\n list serverList == \"A\" as AServers\n\ndo\n log(\"${serverList}\")\n log(AServers)The “AServers“ list will be reduced to sublist containing only the elements that are \"A\". The \"serverList\" will not be available in this KI, as it was only used to create the sublist.
\nserverList = [null]
AServers = [\"A\",\"A\",\"A\"] -→ count = 3
To compare the number of elements in two lists, first ensure both lists exist in the task. Then, you can proceed with comparing their element counts.
\nwhen\n ProcessIssue\n list departmentList\n list serverList\n count(serverList) == count(departmentList)\n\ndo\n log(count(serverList))\n log(count(departmentList))You can copy the entire list in the DO block by previously matching that list in the WHEN block:
\nwhen\n ProcessIssue\n list serverList\n\ndo\n toBeDeletedList = serverListYou can copy some elements from a list into another list using alias:
\nwhen\n ProcessIssue\n list serverList == \"A\" as AList\n\ndo\n toBeDeletedList = AlistIn this example toBeDeletedList will contain only \"A\" elements.
\ntoBeDeletedList = [\"A\",\"A\",\"A\"]
Use the keyword \"add\" to insert a new value into a list.
\nwhen\n ProcessIssue\n list serverList\n\ndo\n add(serverList = \"F\")This will result in:
\nserverList = [\"F\",\"A\",\"B\",\"C\",\"A\",\"C\",\"D\",\"A\",\"E\"]
You can replace a single value using \"keys\"(go to \"keys“ section), otherwise the entire list will be replaced by the unique value you choose.
\nwhen\n ProcessIssue\n list serverList\n\ndo\n set(serverList= \"Z\")Now serverList is:
serverList = [\"Z\"]
You can omit keyword \"set\" and achieve the same result.
\nIn this example:
\nwhen\n ProcessIssue\n list serverList\n\ndo\n delete(serverList)The entire serverList will be deleted.
\nIf you do not explicitly use the keyword \"list\", only one value from the serverList will be utilized, and only that specific value will be removed from the list. However, without using \"keys\" we lack control over which value will be deleted.
\nwhen\n ProcessIssue\n serverList\n\ndo\n delete(serverList)This concept arises from the need to work with lists in Bardioc in an orderly manner.
\n![\"Keys1.png\"](\"/7.0/images/ki-syntax/Keys1.png\")
\nIn this task, you receive two different lists: one containing the process names and the other the process statuses.
\nGiven the following KI, can you guess which values for “processName” and “processStatus” will appear from the log function?
\nwhen\n ProcessIssue\n processName\n processStatus\n\ndo\n log(processName)\n log(processStatus)This conditioning in the WHEN block, will cause the KI to be triggered 9 times to complete all the possible combinations:
\nA – running , A – stopped , A – running
\nB – running , B – stopped , B – running
\nC – running, C – stopped, C – running
This is not what we need. We require accurate information about the status of each process. We are looking for a result like this:
\nA – running
\nB – stopped
\nC – running
To effectively pair both lists, we use keys. Keys allow us to easily fetch and relate information. In the Task Inspector, keys are displayed as labels in square brackets, and we use them similarly in KIs to ensure that information is matched correctly.
\nThe task now looks like this:
\n![\"Keys2.png\"](\"/7.0/images/ki-syntax/Keys2.png\")
\nWhen using keys in KIs, it is essential to maintain the same syntax.
\nwhen\n ProcessIssue\n processName\n processStatus[processName]\n\ndo\n log(processName)\n log(processStatus)This approach involves utilizing the values of one list as “keys” for another list. This KI will be executed 3 times providing the desired outcome:
\nA – running
\nB – stopped
\nC – running
Keys are like labels that help us organize lists within a Knowledge Item (KI). They’re important because they let us pick the right combinations of values when the KI is running. Without keys, the KI would just grab random values from each list, which can be a problem when we need to match up values from different lists logically.
\nUse the keyword add to include a new value and link it to a specific key.\nNOTE: Use set only when replacing an existing value for a given key in a list.
when\n ProcessIssue\n ? list status\n\ndo\n add(status[\"A] = \"running\")\n add(status[\"B] = \"stopped\")\n add(status[\"A] = \"running\")To copy a list that has keys, you need to add square brackets to the new list where you want to copy the content:
\nwhen\n list users\n\ndo\n list userName[] = usersWe are going to be working with the following list:
\nusername = [\n \"age\": \"30\",\n \"age\": \"20\",\n \"age\": \"35\",\n \"age\": \"40\",\n \"age\": \"30\",\n \"age\": \"30\",\n \"country\": \"Spain\",\n \"country\": \"Spain\",\n \"country\": \"Germany\"\n \"country\": \"Spain\",\n \"country\": \"Spain\",\n \"country\": \"Germany\"\n ]
This syntax will keep both lists available (userName and userName[“country”]):
\nWhen\n list userName\n list userName[\"country\"] as countrylist\n\ndo\n log(userName}\n log(\"${countrylist}\")username → log [\"Spain\",\"Spain\",\"Spain\",\"Germany\",\"Germany\",\"Spain\",\"30\",\"40\",\"35\",\"30\",\"20\",\"30\"]
countrylist → log [\"Spain\",\"Spain\",\"Spain\",\"Germany\",\"Germany\",\"Spain\"]
On the contrary, if you access a sublist, the full list is not available unless you specifically reference it.
\nwhen\n list userName[\"country\"] as countrylist\n\ndo\n log(userName}\n log(\"${countrylist}\")log userName doesn’t exist for this KI execution
\ncountrylist → log [\"Spain\",\"Spain\",\"Spain\",\"Germany\",\"Germany\",\"Spain\"]
Using the logic we have just explained let’s see some examples.
\nThis will not work :
\nwhen\n list userName[\"age\"] has \"30\"\n list userName[\"country\"] has \"Germany\"\n\ndo\n log(userName)\n log(userName['age'])\n log(userName['country'])Since list userName[“age”] in the WHEN block narrows down the values from userName for the remainder of the KI execution, userName[“country”] no longer exists within this KI execution.
You could solve this in two ways:
\nUtilizing aliases to store various sublists for checking against different values
\nwhen\n list userName[\"age\"] as age\n age == \"30\"\n list userName[\"country\"] as country\n country == \"Germany\"\n\ndo\n log(userName)\n log(age)\n log(country)userName → doesn’t exists
\nage → log [\"30\",\"40\",\"35\",\"30\",\"20\",\"30\"]
country → log [\"Spain\",\"Spain\",\"Spain\",\"Germany\",\"Germany\",\"Spain\"]
Ensure to first check for existence of the full list before proceeding to check against sublists
\nwhen\n list userName\n list userName[\"age\"] has \"30\"\n list userName[\"country\"] has \"Germany\"\n\ndo\n log(userName)\n log(userName[\"age\"])\n log(userName[\"country\"])userName → log [\"Spain\",\"Spain\",\"Spain\",\"Germany\",\"Germany\",\"Spain\",\"30\",\"40\",\"35\",\"30\",\"20\",\"30\"]
userName[\"age\"] → log [\"30\",\"40\",\"35\",\"30\",\"20\",\"30\"]
userName[\"country\"] → log [\"Spain\",\"Spain\",\"Spain\",\"Germany\",\"Germany\",\"Spain\"]
You cannot compare two count functions in the same line of a KI
\nThis will not work:
\nwhen\n count(userName[\"age\"]) == count(userName[\"country\"])You will need to use an alias for this:
\nwhen\n count(userName[\"age\"]) as CountAge\n count(userName[\"country\"]) == CountAge\n\ndo\n log(CountAge)CountAge → 6
\ncount(username[“country”]) → 6
\nYou can create an alias for each count(list[\"key\"]) and then match both aliases. Alternatively, you can create only one alias and match it against the count of list[\"key\"], as shown in the example above.
Counting number of element by key
\nWhen you want to count the number of elements by key, make sure to first check for the existence of the full list:
\nwhen\n list userName\n count(userName[\"age\"]) as CountAge\n count(userName[\"country\"]) == CountAge\n\ndo\n log(CountAge)This variant will not work:
\nwhen\n username\n count(userName[\"age\"]) as CountAge\n count(userName[\"country\"]) == CountAge\n\ndo\n log(CountAge)| \n\n | \n\nCan you tell why?\n | \n
Naming the list without specifying that it is a list will result in only one value being taken. For example, if username = “Spain”, the two following conditions:
userName[“age”]
\nuserName[“country”]
will never match, because the list now contains only one value: “Spain”.
\nCounting number of occurrences linked to a key
\nIf you want to count the number of occurrences of a specific value within a list based on a key, you need to use an “alias”. The following syntax will cause an error:
\nwhen\n count(userName[\"age\"]==\"30\")\n\ndo\n log(\"This is the number of students that are 30yold: ${count30}\")However, using an alias for this purpose will succeed:
\nwhen\n userName[\"age\"] == \"30\" as age30\n count(age30) as count30\n\ndo\n log(count30)\n log(\"This is the number of students that are 30yold: ${count30}\")count30 → 3
\nSometimes, you may need to retrieve a key value from one list in order to apply it to another list. You can accomplish this by following either of these two examples:
\nwhen\n ProcessIssue\n worklog_entries\n status[worklog_entries] =~ \"Ticket created\"\n\ndo\n entry_number = worklog_entriesThis will provide the key value, which in this case is a number that you can use for further processing lists.
\nwhen\n ProcessIssue\n worklog_entries\n status[worklog_entries] =~ \"Ticket created\"\n worklog_person[worklog_entries]\n\ndo\n log(\"${worklog_person} create incident Ticket\")You can also use the key function to retrieve the key directly:
when\n ProcessIssue\n status\ndo\n log(\"${key(status)}\")When using an alias to reference a specific value from a list and intending to update it, you have the option to replace the current value directly in the list using \"set\", or continue using the alias to consistently update that value.
\nReplace a value with \"set\"
\nwhen\n ProcessIssue\n description == \"elements\"\n status['times']\n\ndo\n set(status['times'] = status['times'] + 1 )Using alias
\nwhen\n ProcessIssue\n description == \"elements\"\n status['times'] as NoTimes\n\ndo\n NoTimes = NoTimes + 1The alias list is updated, and the changes are reflected in the original list: status['times']. Keep in mind that once the alias is created status list is not longer recognized. Therefore in order to update a value, you need to use NoTimes from this point forward.
Note: if you update the value in the list using its corresponding key, you will add a new element to the list rather than replacing the existing one.
\nwhen\n ProcessIssue\n description == \"elements\"\n status['times'] as NoTimes\n\ndo\n status['times'] = NoTimes + 1This will result for each execution in:
\nstatus['times'] = 1
\nstatus['times'] = 2
\nstatus['times'] = 3
Using the keyword “list” affects which values the KI will see during execution. Without it, the list will consider only one random value.
\nWhen accessing multiples values or lists in a KI, always use an alias for at least one of them to ensure proper functionality. This allows you to retain the original list.
\nWhen you need to match against two different values within a list, such as:
\nlist userName['age'] == \"30\"
\nlist userName['country'] == \"Germany\"
the matching process narrows down the available values.
\nAfter list userName['age'] == \"30\" , only values that meet this condition remain for further matching, while others are no longer considered in the execution scope. Therefore, to make a double match, you must first check for the entire list on its own.
list userName
\nlist userName['age'] == \"30\"
\nlist userName['country'] == \"Germany\"
All data is stored as \"magic\" strings. This means each value is stored by default as a string.\nIf numerical operations are applied Bardioc engine will dynamically find the correct interpretation of the string and perform the operation accordingly.
\nData is stored in variables as a list of values (one or more values).\nVariable values are processed in the engine as one of three formats:
\n| Data Type | \nDescription | \n
|---|---|
Arbitrary size integers | \nConsists of only numbers 0-9, as well as an optional\nleading + or -. The value size is limited by available space. | \n
Floating point number | \n\n \nConsists of only numbers \n
| \n
String | \nEverything that is not represented by an integer or floating\npoint number | \n
Converting between the various formats is done dynamically, meaning the\nengine searches automatically for the right storage format for a given\ncharacter sequence. Please note that numerical comparison operators\nautomatically generate a \"false\" if a comparison is made with a string.
\nVariables are always handled with respect to their relative scope. There\nare three scopes for data:
\nNODE - The top level of the MARS model Node data, this represents\nenvironmental data (On)
\nISSUE - The top level of the Issue data, this represents the\nsituational data (When)
\nLOCAL - The current execution context, this is only valid in the\ncurrent block
\nYou can imagine a scope as a \"space\" in which variables exist. The\nblocks in Knowledge Items interact with different scopes.
\non\n Var1\nwhen\n Var2\ndo\n NODE::Var1\n ISSUE::Var2\n LOCAL::Var3on\n NodeName\nwhen\n SendMessage\ndo\n LOCAL::Message = \"${ISSUE::SendMessage} on ${NODE::NodeName}\"\n log(LOCAL::Message)on\n NodeName\nwhen\n SendMessage\ndo\n LOCAL::Message = \"${SendMessage} on ${NodeName}\"\n log(Message)Whenever you need to modify any data from the current execution context (current AutomationIssue or vertex that issue is currently associated with) do it directly by assigning the required value, e.g.
\ndo\n myVar = \"newValue\"\n Node::ogit/status = \"visited\"| \n\n | \n\n \n \nNever use the Graph vertex operations \n\n \n
\n \nto work with data from the current execution context, i.e. from the issue currently being processed \n | \n
| \n\n | \n\nKI Elements used within the On and When blocks are\nlimited to their specific and LOCAL scope.\n | \n
| Block | \nPermitted Scopes | \n
|---|---|
On | \nNODE and LOCAL | \n
When | \nISSUE and LOCAL | \n
Do | \nNODE, ISSUE and LOCAL | \n
For example: A variable created in the NODE scope can not be\nreferenced in When, because When operates in the ISSUE scope. The\nvariable can be referenced from Do since that works across all\nscopes.
| \n\n | \n\nYou can however, compare variable values between the NODE and ISSUE scopes.\n | \n
| \n\n | \n\nMany elements available in the Do block (e.g. Execute,\nJavaScript etc.) allow storing outputs and return codes. You do not have\nto declare global variables to store these. By default the entry fields\nfor these output variables will create temporary variables in the\nLOCAL scope that are discarded after the execution has finished. You\ncan use this to process outputs further and only storing the desired\nfinished results to a defined variable.\n | \n
| \n\n | \n\nThe scope used by Do consists of all data available.\n | \n
When using a with expression the define attribute and edge condition you are creating a separate scope for that expression. This means your match will be relative to the scope of with unless explicitly stated otherwise.
If a variable is available in the NODE/ISSUE/LOCAL scope, it will use these scopes first outside of with. If a variable is ambiguous in which with scope it was defined, the parser will force you to expicitly define the scope.
on\n A\n with test@child:owns as test\n A\n B == A # Will use test::A\n end\n B == A # Will use NODE::ATo correctly address variables, it might be necessary to specify the\nscope in which they exist. To do so you will add an Alias prefix to the\nvariable.
\nFor example: Using \"VarAdd\" in the Do block, you wish to create a\nvariable named Variable1 in the NODE scope. By default, all elements\nin Do will assume the ISSUE scope.
Only specifying Variable1 will create this variable as\nISSUE::Variable1. To properly create the variable in the desired scope,\nyou must specify NODE::Variable1 in your \"VarAdd\" element.
Similarly: To create temporary variables that get discarded after\nexecution you must use LOCAL::Variable1.
| \n\n | \n\n \n \nVariables in different scopes can have identical names but\ncontain different data. Bardioc will try to \"find\" the variable if\nno specific alias is defined. The order in which it will look for\nvariables of the given name is LOCAL then ISSUE then NODE. \n\n \nTo avoid undesired effects, make sure to declare variables uniquely for the\nscopes or use scope Alias to address the desired variable absolutely. \n\n \nThe Editor will prevent you from defining the same variable name in both\nISSUE and NODE scope. You can however create variables in LOCAL scope\nthat have the same name. Make sure you correctly address the variable\nusing the principles described above to process the correct data. \n | \n
Data context - Contains all data scopes and all values contained\ntherein
\nExecution context - Contains exclusively the values referenced in the matching conditions
\nHere you can get an idea how scopes and contexts contain each other:
\n![\"data_context.png\"](\"/7.0/images/ki-syntax/data_context.png\")
\nAt almost every location in a Knowledge Item where strings could be\nentered, the engine also processes \"VarStrings\". VarStrings are strings\nthat can be dynamically expanded during the runtime with specific\nvariable values. This works as follows:
\nIt is possible to construct strings using string interpolation:
\non\n Foo\n Bar == \"Hello, ${Foo}\"It is possible to use math expressions on the right side of a match:
\non\n Foo\n Bar == Foo + 1log(\"This is the ID of the current node: ${NodeID}\")In addition to this simple string replacement, we can perform some mathematical operations:
\n# Addition\nLOCAL::result = number1 + number2\nlog(\"${number1} + ${number2} = ${LOCAL::result}\")# Subtraction\nLOCAL::result = number1 - number2\nlog(\"${number1} - ${number2} = ${LOCAL::result}\")# Division\nLOCAL::result = number1 / number2\nlog(\"${number1} / ${number2} = ${LOCAL::result}\")| \n\n | \n\n \n \nWhen the result of a division is about to be assigned to a variable, if division by 0 was attempted, the value of the variable will be set to 'MathError'. It’s important to note that using 'MathError' in subsequent operations can lead to further arithmetic errors in the following KIs \n | \n
# Multiplication\nLOCAL::result = number1 * number2\nlog(\"${number1} * ${number2} = ${LOCAL::result}\")# Mod\nLOCAL::result = number1 % number2\nlog(\"${number1} % ${number2} = ${LOCAL::result}\")There is also a mathematical library integrated into the engine which allows the\nevaluation of mathematical formulas. For this purpose, the corresponding\nexpression is enclosed in $[ ]:
\n# Multiplication\nlog(\"Calculated Value: $[${number1} * ${number2}]\")The engine also integrates a mathematical library (https://github.com/Rob-bie/expr) that enables the evaluation of mathematical formulas. To use this funcionality, the relevant expression must be enclosed in $[ ].\nWhen including a variable in the mathematical formula, the variable should be enclosed in ${}
# Absolute value\nValue = \"$[abs(-20)]\"\n\n# Absolute value using variables\nTS1 = \"1732542005189\"\nTS2 = \"1732539624000\"\n\nTS3 = \"$[abs(${TS1} - ${TS2})]\"Also, various modifiers can be used in variable strings to convert the\noutput. Let’s assume we have a variable \"data\" with a string as value. We can modify the value \"hello world\" in the following ways:
\n| \n\n | \n\nModifiers must be put before scope declaration, not before variable: ${+LOCAL::test}\n | \n
| \n | Description | \nSample from \"Hello world\" | \n
|---|---|---|
+ | \nConvert to uppercase | \n\"HELLO WORLD\" | \n
- | \nConvert to lowercase | \n\"hello world\" | \n
^ | \nConvert to upper camelcase | \n\"Hello World\" | \n
\\ | \nShell encoding (extra backslash for \" and \\ ) | \n\\\"Hello world\\\" | \n
& | \nHTML encoding | \n"Hello world" | \n
_ | \nConvert non alphanumerical chars to underscore | \nHello_world | \n
upper = \"${+data}\"\nlower = \"${-data}\"\ncamel = \"${^data}\"\nshell = \"${\\data}\"\nhtml = \"${&data}\"\nunder = \"${_data}\"| \n\n | \n\n \n \nThese can also be combined as required, so if the value is\n\"hello world\" as above, you can combine uppercase and underscore conversion ${+_HELLOWORLD} for a result like: HELLO_WORLD. \n | \n
VarStrings allow simple parsing of JSON structures.
\nHandling of JSON structures is initialized by adding # to a variable name inside the VarString followed by operators to address Key:Value pairs inside the structure.
| Operator | \nFunction | \n
|---|---|
| \nName of \"key\" in the root JSON object | \n
| \nName of \"subkey\" in a JSON sub-object | \n
| \nn-th element of a JSON (sub-)array item (first element is 0). | \n
| \nn-th element of a JSON (sub-)array item counted from the end of the array (-1 is the last item). | \n
The following structure shows a minimalist example. We assume the data is stored in the variable \"JSONData\"
\n{\n \"UserInfo\": {\n \"User\": \"Jane Doe\",\n \"Location\": {\n \"Country\": \"Germany\",\n \"City\": \"Frankfurt\"\n },\n \"Pets\": [\n {\n \"Name\": \"Daisy\",\n \"Type\": \"Cat\",\n \"Age\": \"3\"\n },\n {\n \"Name\": \"Duke\",\n \"Type\": \"Dog\",\n \"Age\": \"1\"\n },\n {\n \"Name\": \"Felix\",\n \"Type\": \"Cat\",\n \"Age\": \"97\",\n \"Color\": \"Black\"\n }\n ]\n }\n}Extract the value for \"Country\"
\n${JSONData#UserInfo['Location']['Country']} → \"Germany\"
Extract a full entry from the \"Pets\" array
\n${JSONData#UserInfo['Pets'][1]} → \"{\"Name\":\"Duke\",\"Type\":\"Dog\",\"Age\":\"1\"}\"
Extract the name for the second entry in the \"Pets\" array
\n${JSONData#UserInfo['Pets'][1]['Name']} → \"Duke\"
| \n\n | \n\nYou can only extract single values or objects using this syntax, you can not extract arrays.\n | \n
| \n\n | \n\nIf you need to perform more complex operations on JSON structures, please refer to the JavaScript element.\n | \n
The different Data types are stored as values in variables. This document describes how to manipulate/add/delete values in variables.
\nThere are multiple ways to add or remove variables and their values. Most cases will use the simple assignment notation:
\nSet the variable VarA to the value foobar. Since no specific scope has been specified, it will be created in the default scope, which is always the issue: ISSUE::VarA.
do\n VarA = \"foobar\"The keyword add will add a new value:
add(VarA[\"foo\"] = \"bar\") (1)\nadd(VarA = \"foobar\") (2)| 1 | \nAdds the value \"bar\" to the key \"foo\" stored in Variable VarA | \n
| 2 | \nAdds the value \"foobar\" to the list of values stored in Variable VarA, there was only one value before it will create a list and append | \n
Assignment replaces values:
\nwhen\n VarA\ndo\n VarA = \"foobar\"This will replace the matched value with a new one.
\nWhen you just want to replace the value, regardless what value it had (atomic operation), use this syntax:
\nwhen\n FooVar\ndo\n set(FooVar=\"Bar\")\n #or\n set(FooVar@any = \"Bar\")when\n VarA\n ...\ndo\n set(VarA = \"new value\")when\n # do not match VarA\n ...\ndo\n VarA = \"new value\"when\n # do not match VarA\n ...\ndo\n VarA = [\"A\", \"B\", \"C\"]When you need to set it, independent from the node where the value was assigned:
\nwhen\n VarA\n ...\ndo\n set(VarA@any = \"new value\")when\n # do not match VarA\n ...\ndo\n VarA@any = \"new value\"BarVar = \"Bar\"Note:
\nwhen\n BarVar = \"Foo\"\ndo\n BarVar = \"Bar\"will replace \"Foo\" to \"Bar\"
\nwhen\n ElseVar\ndo\n BarVar = \"Bar\"replaces all Bars which were created on this node to one value \"Bar\"
\nAssignment of a variable:
\ndo\n BarVar = \"Bar\"Assignment of a matched variable behaves differently to assignment of an unmatched variable:
\nwhen\n BarVar == \"Foo\"\ndo\n BarVar = \"Bar\" # will replace \"Foo\" to \"Bar\"when\n ElseVar\ndo\n BarVar = \"Bar\" # replaces all Bars which were created on this node to one value \"Bar\"do\n delete(FooVar)| \n\n | \n\nIssue variables are automatically tracked for the node where they were created by a KI.\nThis way you can access issue variables which were created on another node.\n | \n
delete(FooVar)Note:
\nwhen\n FooVar = \"Foo\"\ndo\n delete(FooVar)will delete FooVar with \"Foo\"
\nwhen\n #Else\ndo\n delete(FooVar)\n # will delete all FooVar created/set on the current node\n #or\n delete(FooVar@any)\n # will delete all FooVar independent on which Node FooVar was created\n #or\n delete(FooVar@any, created_on: SomeOtherNodeID)\n # will delete all FooVar created on SomeotherNode\n #or\n delete(FooVar[\"key\"]@any)\n # will delete all FooVar with \"key\" independent on which Node FooVar was createdwill delete all FooVar matching the conditions
Similar to delete a value:
\nwhen\n VarA\ndo\n delete(VarA)\n delete(VarB@any)When you need to delete some values which were created on a specific node:
\ndo\n delete(VarB@any, created_on: SomeOtherNodeID)Additionally it is possible to specify a key:
\ndo\n delete(VarB[\"test\"]@any)Note that set/delete/assignment with a key will replace/delete only values with the same key.\nFor example:
\nVarA[\"key\"] = \"new value\"This will not affect variables with other keys.
\non\n list VarA\nwhen\n ProcessIssue\ndo\n VarB = VarA # will copy list in VarBon\n list VarA\nwhen\n ProcessIssue\ndo\n VarB[] = VarA # will copy list in VarB with keysYou can count the number of values in a list. You can then match the result for further actions.
\ncount ogit/Automation/MARSNode@in:mars as Count\n ...\nend\nCount > 0on\n list VarA\n count(VarA) > 3Bardioc processes all data values in variables identically. Keying is\nused to \"relate\" data across different variables and therefore being\nable to establish a certain context. Data is stored as single values of\na type depending on how the variable was defined. To use a \"related\" set\nof data each value can be assigned a \"Key\". By setting identical keys\nfor values across multiple variables you can match \"related\" data and\nestablish a more specific execution context.
\nFor example:
\nWe have stored two emails as values in variables:
\nEmailTo:\n - Value: test@almato.com\n - Value: abc@almato.com\nEmailFrom:\n Value: info@almato.com\nEmailBody:\n - Value: \"Dear user this is a reminder to close your window.\"\n - Value: \"Dear user this is a reminder to water your plants.\"\nEmailSubject:\n - Value: \"Please close your window.\"\n - Value: \"Please water your plants.\"We then have a Knowledge Item match to these variables and send out\nemails.
\nAll these values look identical from the data perspective of Bardioc\nand would be combined randomly to produce all possible permutations. To\nhave a more specific context to execute we can add a key to specify\nwhich values \"belong together\" or \"relate\". We simply key all related\ndata with the value of EmailTo that describes the relationship.
EmailTo:\n - Value: test@almato.com\n - Value: abc@almato.com\nEmailFrom:\n Value: info@almato.com\nEmailBody:\n - Value: \"Dear user this is a reminder to close your window.\"\n Key: \"test@almato.com\"\n - Value: \"Dear user this is a reminder to water your plants.\"\n Key: \"abc@almato.com\"\nEmailSubject:\n - Value: \"Please close your window.\"\n Key: \"test@almato.com\"\n - Value: \"Please water your plants.\"\n Key: \"abc@almato.com\"Now we can match all values that have the same key and be sure that only\nthose values are processed together.
\nPlease note: In this specific example the keys happen to be unique and\ndefine exactly one execution context each. In the real world data\nsituations using something like an email address as key can lead to\nundesired execution contexts if there are multiple data relationships\n(for example two different emails for the same recipient). You can\nconsider constructing keys from multiple values and storing them in a\nseparate variable or rewrite your matching conditions to process a more\nprecise context to begin with.
\nThe builtin functions key, created and created_on can be used to access variable metadata.
| Function | \nDescription | \n
|---|---|
| \nGets the key of a matched variable. | \n
| \nGets when the variable was created as a millisecond Unix timestamp. | \n
| \nGets the ID of the node where the variable was created. | \n
They may be used in the right hand side of matches.
\n| \n\n | \n\n \n \nVariable names are limited by the underlying tokenizer to contain: \n\n \n
| \n
Bardioc variables are largely defined by the users. Variables are\ndesigned to be reused throughout the entire Bardioc installation.\nDefined variables are stored in the database and are available for\n(re)use for all users. Typically (with the exception of temporary/local\nvariables) each variable is defined during initial creation to contain a\nspecific type of data e.g.:
\n| Variable | \nDescription | \nContent | \nExample | \n
|---|---|---|---|
IPv4Address | \nContains an IPv4 address. | \nIPv4 address as string. | \n192.168.0.1, | \n
Interface | \nContains a Network interface name. | \nInterface name as\nstring. | \neth0, | \n
| \n\n | \n\n \n \nVariable definitions are immutable once defined, therefore great care\nshould be taken when defining new variables. This should be a process\ninvolving key staff from all groups of Bardioc users. Customers can\nand should define their best practice naming and definition standards\nfor Bardioc variables during the initial rollout process. \n | \n
| \n\n | \n\nMake sure to define all variables you wish to use\nbefore their first occurrence in an Issue.\n | \n
Each Issue must contain at least one \"Todo\"-Variable otherwise it will\nautomatically be marked as \"resolved\" without any actual processing. The\nuser can define variables with a special \"Todo\" flag that are\nexclusively used to track progress. Bardioc will use \"Todo\"-Variables\nto track if a task has been completed. Issues will remain in processing\nuntil all values from all \"Todo\" variables in this Issue have been\nremoved.
\nThe user can create a variable HostIsDown to which a list of hostnames\nthat should be reachable is stored. The variable can contain a list of\nvalues like:
HostIsDown = [\"192.168.1.100\",\"192.168.1.101\",\"192.168.1.102\"]Now a set of Knowledge Items are triggered by the existence of\nHostIsDown and start taking measures to restore service for these\nhostnames. Once they are confirmed to be available again the respective\nhostname is deleted from the list of values in HostIsDown. Once all\n\"Todo\"-Variables have been emptied, the Issue is considered to be\nfinished and will be \"resolved\". As long as there are any values present\nin any of the \"Todo\"-Variables, the Issue will remain in processing\nuntil Knowledge Items have removed all values, the Issue was resolved\nmanually or ejected by other means.
There are a few variables that have special meaning and contain information\nabout the issue processing.
\n| Variable | \nDescription | \n
|---|---|
ogit/_id | \nThe graph ID of the vertex, often referred to as \"issue ID\" | \n
ogit/_created-on | \nTimestamp of issue creation in ms since epoch | \n
ogit/_modified-on | \nTimestamp of last issue modification in ms since epoch | \n
ogit/subject | \nHuman readable issue subject shown in frontend UI | \n
ogit/status | \nCurrent state of the issue | \n
ogit/Automation/originNode | \nID of the vertex the issue was originally created on | \n
ogit/Automation/processingNode | \nID of the vertex the issue is currently attached to | \n
ogit/Automation/processingTimestamp | \nTimestamp value of the last processed KI (ms). It is updated with each KI execution and displayed in the task content | \n
ogit/Automation/deployStatus | \nDeployment status of issue in engine | \n
With the exception of ogit/subject, these variables should be regarded as \"read-only\"\nfor KI processing.
\n[[Self-generated Variables]]\n=== Self-generated Variables
\nThese are variables that are self-generated in the moment that one of the components: Issue, Node or KI exists.
\nIID – it is ogit/_id of an Issue that comes into Bardioc
NodeID – it is ogit/_id of a vertex/Node from the semantic graph
KIID – It is ogit/_id of a KI
These values are auto imported and explicit matching in conditions.
\ndo\n Taskid = IIDThere are variables that will be available only within KI processing context and are not\nactually stored or visible in the graph representation of the issue.
\n| Variable | \nDescription | \n
|---|---|
ExecIdle | \nSeconds since last KI execution. It is dinamically calculated from the ´ogit/Automation/processingTimestamp´ | \n
A simple example that would make use of the ExecIdle variable to trigger a KI only after\nno other KI could be executed for about 5 minutes (only minimal WHEN and DO sections shown):
\nwhen\n ExecIdle > 300\ndo\n log(\"Issue has been idle for 5 minutes\")Let’s illustrate the relationship between ExecIdle and processingTimestamp using the Sleep function. The Sleep function pauses the engine from searching KIs for 10 seconds. During this pause, ExecIdle will be 0 with the last KI execution and will increase over time. Meanwhile, ogit/Automation/processingTimestamp will store the timestamp of the last executed KI. After the 10-second pause, ExecIdle will be 10, and the task will resume, searching for KIs that can complete it.
![\"ExecIdleProcessingTimestamp.png\"](\"/7.0/images/ki-syntax/ExecIdleProcessingTimestamp.png\")
\nCreate a new vertex in Bardioc Graph. For more information about vertices and their properties, please visit this page.
\nThe applicability of this command is limited by the privileges granted to the Bardioc instance\nwhich is used to run it.
\nexit: LOCAL::EXIT,\noutput: LOCAL::OUTPUT = create_vertex(type: <type>, attributes: [<key1>: <value1>, <key2>: <value2>, ...])| Position | \nKeyword | \nRequired | \nDescription | \n
|---|---|---|---|
1 | \ntype | \nX | \nOGIT type of the vertex to be created (e.g. ogit/Person) | \n
| \n | attributes | \n\n | List of attributes to be added to the new vertex. An entry is in the format | \n
| Tag | \nDescription | \n
|---|---|
output | \nBardioc Graph result from the operation | \n
exit | \nResult code of the Bardioc Graph operation, 0 on success, 1 otherwise | \n
output: vertexCreated = create_vertex(type: \"ogit/Person\", attributes: [\n ogit/_owner: \"DT\",\n ogit/email: \"user01@dt.com\",\n \"=/ListTest\": '[{\"nickname1\":\"John\"},{\"nickname2\":\"Johnny\"}]'\n ])Executes actions as defined by the ActionHandler found in the engine’s action handler configuration file actionhandler.json.
exec: LOCAL::RESULT,\nstdout: LOCAL::OUTPUT,\nstderr: LOCAL::ERROR,\nexit: LOCAL::SYSTEMRC = action(capability: \"<capability>\", command: \"<command>\", timeout: <timeout>)| \n\n | \n\nIf exec contains an answer, the other returned values (stdout, stderr, exit) might not have meaningful values.\nYou don’t need to use every tag for each call.\n | \n
| Position | \nKeyword | \nRequired | \nDescription | \n
|---|---|---|---|
1 | \ncapability | \nX | \nOnly ActionHandlers supporting that capability will be selected for execution. | \n
| \n | command | \n\n | Command to execute | \n
| \n | timeout | \n\n | Timeout in seconds that the ActionHandler is allowed to take to perform his task | \n
| Tag | \nDescription | \n
|---|---|
exec | \nResult of the ActionHandlers action | \n
stdout | \nOutput of the operation (stdout) | \n
stderr | \nError output of the operation (stderr) | \n
exit | \nNumeric Exit-Code of the operation | \n
exit: LOCAL::RESULT = action(\n \"ExecuteLocalCommand\",\n command: \"df -h > /mnt/disk_usage.log\"\n ) exit: LOCAL::RESULT = action\n stdout: LOCAL::OUTPUT = action(\n \"ExecuteLocalCommand\", command: \"df -h | grep '/mnt' | awk -F' ' '{print $5}' | tr -d '%'\"\n )Bardioc Engine loads data selectively. What data is loaded is defined by \"matching\" data conditions. The Knowledge Item defines which data should be present, if any of the available data matches this condition it will be loaded into the execution context of the current task. Once data has been added to the execution context it can be manipulated.
\nTo learn about how to manipulate data please refer to the \"Data Manipulation\" section
\nBardioc internally handles all variables as lists which can have multiple values, each with corresponding metadata. During the matching process it is important to be aware of whether you match a variable either as
\na single value from the list or
\nthe full or partial list of values
\nto avoid accidental combinatorial explosion of the solution space and also to use the correct operators to achieve the desired outcome.
\nFor example consider an issue with three variables VarA, VarB and VarC with 10 values 1..10 each. To keep the example as simple as possible metadata will be completely ignored here and the assumption is that nothing in the DO section will invalidate the matching conditions (so none of the 3 variables will be modified).
\nNow for some different matching conditions and the resulting solution space.
\nwhen\n VarA\n VarB\n VarCWill match on each value of each variable and each of the variables will only represent a single value when referenced in the DO section. So the solution space consists of 10*10*10 = 1000 combinations of different values for VarA, VarB and VarC. The KI will be executed for each of these combinations individually.
\nwhen\n list VarA\n list VarB\n list VarCWill match once and each of the variables contains their respective list of values when referenced in the DO section
\nwhen\n VarA\n VarB contains?(VarA)Will match for each of the 10 values of VarA and the same value for VarB. There is one additional matching pair hidden in here as well as VarA == 1 is not only contained in VarB == 1 but also in VarB == 10 as the string \"10\" does contain the substring \"1\".
\nwhen\n list VarA\n list VarB has VarAWill match once as both VarA and VarB contain the same elements.
\nYou can match variables by name or value
\nYou can match nodes by attributes, see [related-nodes]
\nImplicitly assumes exists
not - checks if Variable does not exist
Comparison operators: >= ⇐ == != := =˜
? optional match
?list Variable - match on any value in a list
or condition to string together matches
otherwise implicit and
Variable[\"Value\"] - List contains certain Value
\nMatching on existence of a variable:
\non\n Foo # => Match if Foo exists on the node\n not Bar # => Match only on nodes where the variable Bar does not existThe matching variable should be generally on the left side.
\nFor example:
\non\n Foo # match variable\n Bar == Foo # match Bar and compare to Foo, `Foo == Bar` would be incorrectMatching on not existence of a variable:
\nnot Foo # => Match if Foo variable does not exist\nnot Foo == \"hello\" # => Match if variable Foo does not contain a value \"hello\"Note that the \"not\" does only affect the next expression and has higher precedence than an \"or\" for example, so
\nnot Foo or Foo == \"hello\"means \"Foo does not exist or it does exist and there is a value 'hello' contained within it\". If you want to have a logic to check for \"Foo does not exist or does exist and does not have a value 'hello'\" you would have to use
\nnot Foo or not Foo == \"hello\"Logical or must be explicitly defined.
\nFoo == 1 or Foo == 10All conditions are connected by a logical and.
\nFoo == 1\nBar == 10Each condition is exclusive and matching the same variable multiple times will only add the last match to the context. If you need to match multiple values in the same variable, please assign an Alias to the value like:
\nA == 1\nA == 3 as A1This adds both the value 1 and 3 to the context. If you simply add A == 3 the match will be overwritten and 1 will not be in the context.
| \n\n | \n\nThis behavior is necessary to reuse variables and support multiple conditions for the same variable.\n | \n
You can check for the existence of multiple values in a variable using the has statement. This works for one or more values at once.
| \n\n | \n\nYou can use a pipe (|) to perform an implicit \"or\" match.\n | \n
on\n list A has \"A\" (1)\n list A has \"B\" (2)\n list A has [\"A\", \"B\"] (3)\n list A has \"C\" | [\"D\", \"E\"] (4)| 1 | \n# list has value \"A\" | \n
| 2 | \n# list has value \"B\" | \n
| 3 | \n# list has values \"A\" and \"B\" | \n
| 4 | \n# list has or \"C\" or both \"D\" and \"E\" | \n
A more complex example showing how to check that all values present in a different variable are a subset of a variable:
\nwhen\n list RequiredValues as RequiredSubset\n list CurrentMatch has RequiredSubset\ndo\n log(\"CurrentMatch has all elements contained in RequiredValues\")Use in to check whether a variable appears in a list:
on\n Name in [\"Waldo\", \"Wenda\"]Return the number of matched elements
\non\n list A == \"SearchValue\"\n count(A) > 3 # matches if list A contains more than 3 \"A\" valuesNow if you need to count something and there isn’t an existing variable for it, you can accomplish this using optional variables.
\nwhen\n ? count := 0\ndo\n count = count + 1Values added to variables during KI execution will implicitly remember their point of origin in the graph and will by default only be available for matching when their origin node is part of the current KI execution scope (e.g. was referenced in the ON section of the KI).
\nThe following example would add value \"test\" with origin vertex \"Node1\":
\non\n ogit/_xid == \"Node1\" # will only be executed on \"Node1\"\nwhen\n not Foo@any # must not have any values for Foo created anywhere\ndo\n Foo = \"test\" # add value \"test\" created on \"Node1\" to FooThis value would by default not be considered for matching on Node2 in the following KI as only values created on Node2 itself would be regarded as \"in scope\":
\non\n ogit/_xid == \"Node2\" # will only be executed on \"Node2\"\nwhen\n Foo # would only match values created on \"Node2\"\ndo\n log(\"There is a Foo created on Node2\")In order to match values not created on the current node, the optional graph scope limiter can be specified access this variable from any other node:
\non\n ogit/_xid == \"Node2\" # will also only be executed on \"Node2\"\nwhen\n Foo@any # will match values created anywhere\ndo\n log(\"Foo => ${Foo}\") # logs \"Foo => test\"Other than @any which will match values created on any node in the graph there is also the @self mode which will enforce matching only values created on the local node even if another one is in the current scope (see the following section about related nodes).
\non\n ogit/_xid == \"Node2\"\n with ogit/Automation/MARSNode@parent:ogit/relates\n ogit/_xid == \"Node1\" # will add \"Node1\" to the default scope\n end\nwhen\n Foo@self # will still only match values created on \"Node2\"\ndo\n log(\"got a Foo value\")Sometimes you need to match on more information than available on a single node.\nYou can match also on related nodes. Note that this will automatically add values created on that related node to the default matching scope.
\non\n Foo\n with FooType@in\n Foo == \"has childs\"\n endIf you need to access matched variables:
\non\n Foo\n with FooType@in as Parent\n Foo\n endAfter this it is possible to access Foo, with NODE::Foo and Parent::Foo.
Use the special keyword 'count' to get the number of related nodes matching specific requirements:
\non\n Foo\n count FooType@in as ParentCount\n Bar == \"test\"\n end\n Bar > ParentCount ogit/_type = ogit/Person\n count ogit/ConfigurationItem@out:ogit/_created as CreatedConfigurationCount\n ogit/_id\n endThe alias then contains the determined number of nodes.
\nYou can mark a variable as 'optional', so it can match for KI execution also\nif it does not exist. In this case, it is set to the provided default value:
\non\n ? Count := 0It possible to use matching there, conditions, key and graph position (For example: @any)
on\n ? Count < 5 := 0For list, there is no need to have default values:
\non\n ?list ValuesThis will match in any case, if values exist or not.
\nFor printing list, it is possible to use JSON modifier:
\n log(\"${#Values}\")For no values it will print empty list [].
It is possible to use direct keys for matching.\nFor example to match the IP address for a matched interface:
\non\n Interface\n IP[Interface]The above reads as: If the variable Interface has the value \"eth0\" this will become IP[\"eth0\"].
\nIn contrast to the above the variable Foo in the example below has the value \"key\". It is still possible to combine an expression like that with other matching operations:
\non\n Bar\n Foo[\"key\"] == Bar| \n\n | \n\nIf it doesn’t starts with a digit, then it is numerically 0.\n | \n
The operators == and != transform strings to numbers if possible before comparison.\nIf this is not possible, the operators compare the values as strings.\nIn most cases this is the desired behavior, but if you need to compare strings\nwithout explicit transformation to numbers, use === / !== instead.
| Operator | \nFunction | \nNumerical | \nString | \n
|---|---|---|---|
== | \n\n | X | \nX | \n
!= | \n\n | X | \nX | \n
\n === \n | \n\n | X | \nX | \n
!=== | \n\n | X | \nX | \n
>= | \n\n | X | \n\n |
<= | \n\n | X | \n\n |
> | \n\n | X | \n\n |
< | \n\n | X | \n\n |
=~ | \n\n | \n | X | \n
!~ | \n\n | \n | X | \n
| \n\n | \n\n>, <, <=, >= forces to convert the string to a digit.\n | \n
| \n\n | \n\nFor numerical comparisons and 2.5ABC is 2.5\n | \n
“2” == “2.0\" # true. (1)\n“2bc” == “2.0\" # false (2)\n\"1\" === \"1.0\" # false (3)\n“2bc” > “1.0\" # true (4)\n\"ABC2.5\" > 0 # false (5)\n\"2.5ABC\" == \"2.5\" # true (6)| 1 | \nNumerically equal. | \n
| 2 | \n== falls back to strings if it not comparing 2 numeric values. | \n
| 3 | \nNot an exact match. | \n
| 4 | \nWhen value starts with digit it is assumed to be a numerical and is compared numerically. Alphabetical characters are ignored. | \n
| 5 | \nNumerically ABC2.5 is 0 | \n
| 6 | \nFirst part is interpreted as digits | \n
Matching on equality of variable. Matches strings and numbers (strings will be transformed to numbers)\n:
\nFoo\nBar == FooAdditionally the following comparisons are supported
\nFooN\nBarN == FooN +1\n\nFooT\nBarT == \"Hello, ${FooT}\"Matching on not equality of variable. Matches strings and numbers (strings will be transformed to numbers)
\nFoo\nBar != FooMatching on equality of variable. Matches string without transformation.
\nFoo\nBar === FooMatching on not equality of variable. Matches string without transformation.
\nFoo\nBar !== FooMatching on greater than.
\nFoo\nBar > FooMatching on greater or equal than.
\nFoo\nBar >= FooMatching on less or equal than.
\nFoo\nBar <= FooMatching on less than.
\nFoo\nBar < FooMatch if regular expression matches.
\nRegex literals with slashes can be used to add modifiers.\nFor example, these two matches are the same because the second does case-insensitive matching:
\nFoo =~ \"[Ff][oO]*\"\nFoo =~ /fo*/iA named group in a regex literal binds its submatch as a variable. This lets you match and extract in one step, instead of repeating the same pattern in a regex() call later in the Knowledge Item:
on\n Hostname =~ /^(?<Site>[a-z]+)-(?<Idx>[0-9]+)$/\ndo\n log(\"site ${Site}, index ${Idx}\")The captured variable lives in the scope of the match: NODE in an on section, ISSUE in a when section, and the scope of the surrounding block when matching on related nodes (so Parent::Ver for a with FooType@in as Parent block). It is not treated as a graph attribute, so it never appears in the Knowledge Item’s required-variable set.
A scope-qualified left side moves the match into that variable’s scope, and the capture follows it there:
\non\n A\nwhen\n NODE::Hostname =~ /^(?<Site>[a-z]+)-/ (1)\ndo\n log(\"${NODE::Site}\")| 1 | \nSite lives in NODE, not in ISSUE | \n
A group that takes part in no alternative binds an empty string, following PCRE semantics:
\non\n Flag =~ /^(?:(?<Yes>yes)|(?<No>no))$/ (1)| 1 | \na value of \"no\" binds Yes to the empty string and No to \"no\" | \n
If two regexes in the same section capture the same name, the later match wins:
\non\n Hostname =~ /^(?<X>[a-z]+)-/\n Release =~ /^v(?<X>[0-9]+)$/ (1)| 1 | \nwith \"berlin-42\" and \"v9\" this binds X to \"9\" | \n
A list match keeps only the values that match the regex, so a named group binds one submatch for each value the regex kept, in the same order:
on\n list Hostname =~ /^(?<Site>[a-z]+)-(?<Idx>[0-9]+)$/ (1)\ndo\n log(\"sites ${Site}, indexes ${Idx}\")| 1 | \nwith the values \"berlin-1\" and \"hamburg-2\" this binds Site to \"berlin\",\"hamburg\" and Idx to \"1\",\"2\" | \n
The captured list and the variable’s own binding cannot drift apart, because a value that fails the regex leaves behind neither a value nor a submatch:
\non\n list Hostname =~ /^(?<Site>[a-z]+)-/ (1)| 1 | \nwith \"berlin-1\", \"42-x\" and \"koeln-9\" this binds Hostname to \"berlin-1\",\"koeln-9\" and Site to \"berlin\",\"koeln\" | \n
If only one value survives, the capture is a single-value list, which renders as a bare value like any other single-value list.
\nEach capture list pairs with the values its own regex kept. Matching the same list variable a second time filters the values the first match kept, so a capture on the second regex can end up shorter than the variable’s binding:
\non\n list H =~ /^b/\n list H =~ /(?<D>[0-9])$/ (1)| 1 | \nwith \"berlin-1\", \"berlin-x\" and \"koeln-1\" this binds H to \"berlin-1\",\"berlin-x\" but D only to \"1\" | \n
A named group binds when the left side is a function called on a variable:
\non\n A\n slice(A, 0, 3) =~ /^(?<Prefix>[a-z]+)$/\ndo\n log(\"prefix ${Prefix}\")A function that collapses a list into a single value binds a single value rather than a list, because there is only one result to match:
\non\n list A\n join(A, \"_\") =~ /^(?<First>[a-z]+)_/ (1)| 1 | \nwith the values \"berlin\" and \"koeln\" this binds First to \"berlin\", not to a list | \n
A constructed string on the left side captures the same way:
\non\n B\n \"host-${B}\" =~ /^host-(?<Idx>[0-9]+)$/ (1)| 1 | \nwith B bound to \"42\" this binds Idx to \"42\" | \n
A named group becomes a variable only where the match can bind one. Everywhere else it stays an ordinary regex group: nothing is bound, and the match behaves exactly as it would without the name. A named group written only to document what a subexpression means therefore never stops a Knowledge Item from compiling.
\nA named group does not bind:
\nwith !~ or not — a negated match has no submatches
on an optional match, such as ? Foo =~ /^(?<X>[a-z]+)$/ := \"none\"
in a string-form pattern, such as Foo =~ \"(?<X>[a-z]+)\". The names have to be known when the Knowledge Item is compiled, which a string pattern cannot guarantee, so this applies whether or not the string interpolates a variable
on a function result where the function is not called on a variable, such as slice(\"abc-1\", 0, 3) =~ /^(?<X>[a-z]+)$/
when the same name is matched as a variable, as described in [capture-name-clash]
\nReferring to a name that was never bound makes the Knowledge Item fail to compile, with referencing unmatched variable.
| \n\n | \n\nOnly a named group is affected. Unnamed groups such as Foo !~ /^([a-z]+)-/ bind nothing anywhere and remain valid in every one of the positions listed above.\n | \n
| \n\n | \n\n(?⇐ and (?<! are lookbehind assertions, not named groups, and are unaffected by any of the above.\n | \n
A variable the Knowledge Item matches always wins over a capture of the same name. The group stays decoration, and the name keeps referring to the matched variable:
\non\n Site\n Hostname =~ /^(?<Site>[a-z]+)-/ (1)| 1 | \nSite is the matched variable, not the submatch | \n
The order makes no difference, so matching the variable after the regex behaves the same way. Neither does the scope: a variable matched in an on section also wins over a capture of the same name in a when section. Naming a capture after the variable being matched, as in Foo =~ /^(?<Foo>[a-z]+)$/, is this same case — Foo keeps the matched value.
Only the clashing name is affected. Every other name in the same regex binds as usual:
\non\n Site\n Hostname =~ /^(?<Site>[a-z]+)-(?<Idx>[0-9]+)$/ (1)| 1 | \nSite is the matched variable, while Idx binds \"1\" from a Hostname of \"berlin-1\" | \n
Two [or] branches capturing the same name are not a clash. That is the supported way to capture the same name from alternative patterns:
\non\n Host =~ /^a-(?<Rest>.+)$/ or Host =~ /^b-(?<Rest>.+)$/ (1)| 1 | \nRest binds \"one\" for a Host of \"a-one\", and \"two\" for \"b-two\" | \n
Match if regular expression does not match.
\nFoo !~ \"[Ff][oO]*\"\nFoo !~ /foo*/i| \n\n | \n\nAlias names must be unique. If you use the same name for multiple aliases the Knowledge Item will fail to verify and compile.\n | \n
| \n\n | \n\nAliases can only be assigned to variables, not to values. So somevar as AliasName will work, \"String with $somevar\" as AliasName will not.\n | \n
Sometimes one needs to access different variables with the same name.\nIf you have more than one source variable that may contain the same required information, you can use an alias to match either one and access it later with a fixed name. The first matching variable will provide the value that is returned from the alias:
\non\n alias as FooBar\n Foo\n Bar\n end\ndo\n log(\"we have found value ${FooBar}\")If matching different values from a variable list, an alias must be used to distinguish the values. If no alias is used, the same list entry is expected to match both conditions.
\nwhen\n Foo == \"first\" as FooAlias\n Foo == \"second\"\ndo\n log(\"we have ${FooAlias} and ${Foo} values\")(the example will output \"we have first and second values\")
\nThis is basically the same as a variable alias but will preserve the whole value list of a variable instead of a single value.
\nBar\nlist Foo as AllFoos\nFoo[Bar]| \n\n | \n\n \n \nBardioc stores integer and float values as strings unless there are math operations in the conditions so you can apply these operations to numerical values as well. E.g.: \n\n \nVariable A with value of \"100.0\" \n\n \n\n \nWill match Variable A positively because the value starts with a valid substring. \n | \n
The following examples will check for matching values in variable A. If the string starts with/ends with/contains the substring \"foo\" it will evaluate to \"true\" and match. Otherwise it will be \"false\" and no match.
Checks whether the string given as first argument starts with the string given as second argument.
\non\n starts_with?(A, \"foo\")\nwhen\n ProcessIssue\ndo\n log(\"${A}\")Checks whether the string given as first argument ends with the string given as second argument.
\non\n ends_with?(A, \"foo\")\nwhen\n ProcessIssue\ndo\n log(\"${A}\")Checks if a string contains another string.
\nThis does only work on two strings and is not a list operator. Use HAS if you need to check contents of lists instead.
\non\n contains?(A, \"foo\")\nwhen\n ProcessIssue\ndo\n log(\"${A}\")Create a new edge between two vertices in Bardioc Graph.
\nThe applicability of this command is limited by the privileges granted to the Bardioc instance\nwhich is used to run it.\nFor detailed information on OGIT models, please visit this page.
\nexit: LOCAL::EXIT,\noutput: LOCAL::OUTPUT = connect(vertex_out: <vertex_out_id>, verb: <ogit_verb>, vertex_in: <vertex_in_id>)| Position | \nKeyword | \nRequired | \nDescription | \n
|---|---|---|---|
| \n | vertex_out | \nX | \nThe ID of the Bardioc Graph vertex the edge is originating from | \n
| \n | verb | \nX | \nThe OGIT verb id of the connection to be created (e.g. \"ogit/generates\" or \"ogit/owns\") | \n
| \n | vertex_in | \nX | \nThe ID of the Bardioc Graph vertex the edge is pointing to | \n
| Value | \nDescription | \n
|---|---|
output | \nBardioc Graph result from the operation | \n
exit | \nResult code of the Bardioc Graph operation, 0 on success, 1 otherwise | \n
exit: LOCAL::RESULT = connect(vertex_out: \"MySoftwareNodeID\", verb: \"ogit/relates\", vertex_in: \"MyMachineNodeID\")Generate a string representation of the current or given date(in timestamp format). You can either get the current date in a choosen format or convert a given timestamp into a formatted date string.
\nresult: LOCAL::DATE = dateprint(timestamp: <numerical_timestamp>, format: <format string>)| Position | \nKeyword | \nRequired | \nDescription | \n
|---|---|---|---|
1 | \ntimestamp | \n\n | A numerical timestamp in \"ms since epoch\", defaults to current system time | \n
2 | \nformat | \n\n | A *strftime (convert date and time to a string) compatible format string, defaults to \"%Y-%m-%d %H:%M:%S\" | \n
3 | \ntimezone | \n\n | An optional timezone name to convert the timestamp to (e.g. \"CET\"), defaults to \"UTC\" | \n
\n*Refer to the strftime function documentation to explore all suppported date and time format conversions.\n
| Value | \nDescription | \n
|---|---|
result | \nThe resulting string representing the timestamp | \n
Get current date with a given format
\n result: LOCAL::DATE = dateprint(format: \"%Y-%m-%d %H:%M:%S %Z\")\n log(\"Current Date formatted for year then month then day then time: ${LOCAL::DATE}\")\n # This will result in: \"Current Date formatted for year then month then day then time: 2024-11-26 09:15:30 Etc/UTC\"\n\n\n result: LOCAL::DATE = dateprint(format: \"%A, %Oe, %B %Y %H:%M:%S\")\n log(\"Current Date formatted for day of the week, day of the month, year and time ${LOCAL::DATE}\")\n # This will result in: \"Current Date formatted for day of the week, day of the month, year and time: Tuesday, 26, November 2024 09:54:07\"Convert a given timestamp into a choosen date format
\n LOCAL::DATEMS = 1732622417088\n result: date = dateprint(timestamp: LOCAL::DATEMS, format: \"%d.%m.%Y\")\n log(\"Date formatted for timestamp: ${date}\")\n # This will result in: \"Date formatted for timestamp: 26.11.2024\"Convert a given timestamp into a choosen date format in specific timezone
\n LOCAL::DATEMS = 10000000\n\n result: date = dateprint(timestamp: LOCAL::DATEMS, format: \"%d.%m.%Y %H:%M\")\n log(\"Date formatted for timestamp: ${date}\")\n # This will result in: \"Date formatted for timestamp: 01.01.1970 02:46\"\n\n result: date = dateprint(timestamp: LOCAL::DATEMS, format: \"%d.%m.%Y %H:%M\", timezone: \"CET\")\n log(\"Date formatted for timestamp: ${date}\")\n # This will result in: \"Date formatted for timestamp: 01.01.1970 03:46\"Remove a vertex from Bardioc Graph.
\nThe applicability of this command is limited by the privileges granted to the Bardioc instance\nwhich is used to run it.
\nexit: LOCAL::EXIT,\noutput: LOCAL::OUTPUT = delete_vertex(id: <vertexid>)| Position | \nKeyword | \nRequired | \nDescription | \n
|---|---|---|---|
1 | \nid | \nX | \nThe ID of the Bardioc Graph vertex to be read | \n
| Value | \nDescription | \n
|---|---|
output | \nBardioc Graph result from the operation | \n
exit | \nResult code of the Bardioc Graph operation, 0 on success, 1 otherwise | \n
exit: LOCAL::EXIT,\noutput: LOCAL::OUTPUT = delete_vertex(id: \"cln8tg3pa0fpl01868wmrpcjl_clwg9i9aooy9b0144i86vlzco\")Create a new Issue to be processed by Bardioc Engine. The resulting issue will automatically have the ID of the current issue stored in the \"ogit/Automation/parentIssue\" variable.
\nissue_id: LOCAL::ISSUE_ID = create_issue(<var1>: <value1>, <var2>: <value2>, ...)| Position | \nKeyword | \nRequired | \nDescription | \n
|---|---|---|---|
| \n |
| \n\n | Additional variable with optional value to be added to the issue | \n
| Varname | \nValue set by engine (if not provided) | \nBehavior if value is provided through KI | \n
|---|---|---|
| \nnode ID where parent issue is currently being processed, i.e. new issue will start it’s life on same node | \nnew issue will start it’s life on specified node | \n
| \nID of issue currently being processed | \ninformation of (real) parent might get lost | \n
| Tag | \nDescription | \n
|---|---|
issue_id | \nID of the created issue | \n
issue_id: LOCAL::ISSUE_ID = create_issue(\nSolveTask: \"SomeID\",\nAdditionalData[\"SomeID\"] = \"Data for SomeID\"\n)issue_id: LOCAL::ISSUE_ID = create_issue(\nogit/Automation/originNode=\"xxxxxxxxxxxxxxxxxx\",\nogit/subject=\" Task: check Windows Machine\",\nPerformHealthCheck: \"true\"\n)The current Issue is \"ejected\" from engine processing and set into WAITING state. Ejected Issues will not be picked up for processing until externally set back to PROCESSING state.
\neject_issue(message: <stop message>, issue_id: <issue_id>)| Position | \nKeyword | \nRequired | \nDescription | \n
|---|---|---|---|
1 | \nmessage | \n\n | Message to be set as eject reason for deployStatus, defaults to \"ejected by KI $KIID\" | \n
2 | \nissue_id | \n\n | ID of the Issue to be ejected, by default the current one is used | \n
eject_issue(message: \"Wait for approval\") eject_issue(message: \"Wait for approval\", issue_id: ISSUE:ogit/_id)This example could be used for situations where you need to eject a parent issue for example.
\nRemove an edge between two vertices in Bardioc Graph.
\nThe applicability of this command is limited by the privileges granted to the Bardioc instance\nwhich is used to run it.
\nexit: LOCAL::EXIT,\noutput: LOCAL::OUTPUT = disconnect(vertex_out: <vertex_out_id>, verb: <ogit_verb>, vertex_in: <vertex_in_id>)| Position | \nKeyword | \nRequired | \nDescription | \n
|---|---|---|---|
| \n | vertex_out | \nX | \nThe ID of the Bardioc Graph vertex the edge is originating from | \n
| \n | verb | \nX | \nThe OGIT verb id of the connection to be removed (e.g. \"ogit/generates\" or \"ogit/owns\") | \n
| \n | vertex_in | \nX | \nThe ID of the Bardioc Graph vertex the edge is pointing to | \n
| Value | \nDescription | \n
|---|---|
output | \nBardioc Graph result from the operation | \n
exit | \nResult code of the Bardioc Graph operation, 0 on success, 1 otherwise | \n
| \n\n | \n\nThe Execute element is a simpler frontend to the\nAction element.\n | \n
Executes a command or a script on a certain machine.
\nstdout: LOCAL::STORETO,\nstderr: LOCAL::STOREERROR,\nexit: LOCAL::STORESTATUS = execute(\"echo testing execute\", host: \"_AAE_\", timeout: <timeout>, scriptmode: \"TRUE\")Actually this is just a simpler frontend to specific Action capabilities depending on whether host is set to _AAE\\_ for local execution and ScriptMode is set:
| \n | host=_AAE\\_ | \nHost='anything else' | \n
scriptmode | \nRunLocalScript | \nRunScript | \n
no scriptmode | \nExecuteLocalCommand | \nExecuteCommand | \n
| Position | \nKeyword | \nRequired | \nDescription | \n
|---|---|---|---|
1 | \n\n | X | \nCommand to execute | \n
| \n | host | \n\n | Hostname of the machine where the command should be executed - If the value is '_AAE\\_' the command is executed locally on the automation engine | \n
| \n | scriptmode | \n\n | If this tag exists the content of the command tag is first written into a file and then the file is executed. | \n
| \n | timeout | \n\n | Maximum Time (in seconds) the command may run before it is canceled (default 120 = 2 minutes). | \n
| Tag | \nDescription | \n
|---|---|
stdout | \nOutput of the operation (stdout) | \n
stderr | \nError output of the operation (stderr) | \n
exit | \nNumeric Exit-Code of the operation | \n
output: ExecuteOutput,\n error: LOCAL::Error = execute(\"path/to/script\", timeout: 60)The count function works for lists, and can determine the number of elements in a list.
\nThe applicability of this command is limited to lists.
\n= count(list)| Position | \nKeyword | \nRequired | \nDescription | \n
|---|---|---|---|
1 | \nlist variable | \nX | \nlist of elements | \n
NumberUsers = count(userNameList)The current Issue will be directly moved to another model node that does not need to be connected to the current processing node.
\ngoto(node_id: <node_id>)| Position | \nKeyword | \nRequired | \nDescription | \n
|---|---|---|---|
1 | \nnode_id | \nX | \nNode ID of the node the issue should move to after finishing the KI | \n
goto(\"cln8tg3pa0fpl01868wmrpcjl_xxxxxxxxxxxxxxxxxxxxxxxx\")The function arguments are either unnamed ordered ('positional') or named ('keyword'), depending on the called function.\nPositional arguments must be provided in the exact order defined by the function´s parameter list.\nKeyword arguments instead, specify the parameter name along with its value, allowing you to pass arguments in any order.
\n| Type | \nExample | \n
|---|---|
Positional: \"1\" (Execute echo command) | \n
| \n
Keyword: \"command\" (Execute echo command) | \n
| \n
Some function arguments can be stated as either keyword or positional argument. In that case, both arguments are present in the argument description at the according function.
\n
Let´s explore how to use positional and keywork arguments in function calls.
\nThese are the syntax and arguments description for the regex function:
\nresult: LOCAL::RESULT = regex(\"<text to be matched>\", expression: \"<regex expression>\")| Position | \nKeyword | \nRequired | \nDescription | \n
|---|---|---|---|
1 | \nstring | \nX | \nString onto which the regex is applied | \n
2 | \nexpression | \nX | \nRegular Expression, needs exactly one SubMatch-Pattern. e.g. \"Value: (0-9+) Seconds\" | \n
This is an example of how it can be written in a KI:
\n# Using Positional arguments\nresult: LOCAL::RESULT = regex(\"Here is a hidden value 47.11 inside\", \".*value ([0-9.]+) .*\")\n\n# Using Keyword arguments\nresult: LOCAL::RESULT = regex(expression: \".*value ([0-9.]+) .*\", string:\"Here is a hidden value 47.11 inside\")\n\n# Combining Positional and Keyword arguments\nresult: LOCAL::RESULT = regex(\"Here is a hidden value 47.11 inside\", expression: \".*value ([0-9.]+) .*\")The function results are returned as tagged values, and matched to variables using the syntax:
\n<tag>: <var>,\n<tag2>: <var2> [...] = function(...)add
\ndelete
\nset (assign)
\nkey
\ncreated
\ncreated_on
\nNote: For any graph object being \"in scope\" (at least the issue itself and\nthe current processing node) it’s always preferred to apply modifications directly\n using add, set/assignment, delete.
Managing vertices:
\nManaging edges:
\nQuerying the graph:
\nManaging timeseries data:
\nManaging attachments:
\nFind or create(if none is found) a timeseries with given attributes attached to the current or provided vertex (ogit/Timeseries).
\nThe Timeseries is a vertex in the Bardioc graph used primarily to record temporary data points.This vertex can be attached to various types of Nodes in the graph, enabling later the retrieval of timestamps with their values.
\nThere are two types of timeseries used by the engine: \"History\" and \"Minimal History\"(a trimmed version of History used to restore correct state of a task). These should not be modified, though they can be read.
\nYou can name new timeseries as you wish.
\nIf you only need to search for a timeseries, use a vertex query.
\nThe applicability of this command is limited by the privileges granted to the Bardioc instance\nwhich is used to run it.
\nexit: LOCAL::EXIT,\noutput: LOCAL::OUTPUT = find_timeseries(<name of the timeseries>, attributes: [<key1>: <value1>, <key2>: <value2>, ...] , [ nodeid: <vertex id>])| Position | \nKeyword | \nRequired | \nDescription | \n
|---|---|---|---|
1 | \nname | \nX | \nName of the timeseries to be created | \n
| \n | attributes | \n\n | List of attributes defining the timeseries. Create an entry in the format | \n
| \n | nodeid | \n\n | Optional ID of the vertex the timeseries should be attached to, default is the current vertex. | \n
| Tag | \nDescription | \n
|---|---|
output | \nThe ID of the timeseries found or generated | \n
exit | \nResult code of the Bardioc Graph operation, 0 on success, 1 otherwise | \n
exit: LOCAL::EXIT,\noutput: TS_ID = find_timeseries(\"Temperature History\", attributes: [\"ogit/name\" : \"Temperature tracking\", \"ogit/unit\" : \"SPP\" ], nodeid: \"KIID\")This will create a timeseries \"Temperature History\" if it doesnt already exist. TS_ID will contain the timeseries ID for further processing.
| \n\n | \n\nAvoid using if constructs for large algorithms in a single KI. Please see the Logical Branching section for more information.\n | \n
if allows conditional execution. It contains a condition to be evaluated first. If the condition is true, the then block gets executed. Otherwise if the condition is false, the optional else block gets executed.
The if block will check the exit code of a command:
stdout: ExecuteOutput,\nexit: Error = execute(\n\"/some/command/path -with arguments\",\nhost: \"_AAE_\"\n)\n\nif Error then\n log.error(\"command exited with non-zero exit code\")\nelse\n log(\"execute returned ${ExecuteOutput}\")\nendThe following example will check the numerical exit code of a command:
\nif LOCAL::CODE == \"0\" then\n persData = \"extracted\"\n delete(GetPersonData)\nelse\n persData = \"failed\"\n log(\"failed to get data for Person: ${persNo}\")\nendYou can also use \"and\" and \"or\" to consider multiple conditions within a single if block.
if LOCAL::CODE == \"0\" and LOCAL::Status == \"SUCCESS\" then\n persData = \"extracted\"\n delete(GetPersonData)\nendWrite a message into the logfile of the engine. It is mainly used for debugging purposes.\nYou can optionally specify the log level by appending it to the log command.
log(\"<message>\")\nlog.error(\"<errormsg>\")| Log Option | \nLog Level | \n
|---|---|
log | \ninfo (default) | \n
log.debug | \ndebug | \n
log.info | \ninfo | \n
log.warn | \nwarning | \n
log.error | \nerror | \n
| Position | \nKeyword | \nRequired | \nDescription | \n
|---|---|---|---|
1 | \n\n | X | \nMessage to write in the log. | \n
log(\"This is a log message\")\nlog(\"Final sum is: ${totalSum}\")\nlog(totalSum)To display the content of a variable within the log function, you have the option of using \"${varName}\" along with any string .Alternatively, you can simply reference the variable by its name alone as seen in the examples above.
\nlog\tinfo(\"default\")\nlog.debug(\"debug\")\nlog.info(\"info\")\nlog.warn(\"warning\")\nlog.error(\"error\")Use JavaScript expressions to assign values to variables.
\nBardioc contains a full JavaScript engine that can be used to manipulate data.
\n| \n\n | \n\nThe JavaScript interpreter does not support the use of external 3rd party libraries.\n | \n
JavaScript Engine | \nGoogle V8 (Version 7.7.299.13-node.16) | \n
Script Standard | \nECMAScript 2019 | \n
Executed on | \nNode 12 | \n
The JavaScript element allows processing data within a Knowledge Item.\nThe final \"result\" returned by the element will be stored in the Variable specified in the StoreTo field.
If the JavaScript expression returns, for example, a list of filenames it will store this list as a single long value. You can use further\nprocessing of the output to store the results as separate values for each line/each entry in an array or a map of \"Key:Value\" pairs (see examples below).
\nexit: LOCAL::EXIT\nresult: LOCAL::RESULT = javascript(\"<js-script>\")Default timeout for javascript execution is 5 seconds, but can be extended upto 600 seconds by providing the 2nd optional argument:
\nexit: LOCAL::EXIT\nresult: LOCAL::RESULT = javascript(\"<js-script>\", 20)Also named options are supported:
\nexit: LOCAL::EXIT\nresult: LOCAL::RESULT = javascript(timeout: 30, code: \"<js-script>\")If specified timeout is more than 10 minutes, timeout is reset back to default (5 seconds).
\n| Position | \nKeyword | \nRequired | \nDescription | \n
|---|---|---|---|
1 | \n:code | \nX | \nScript to be evaluated | \n
2 | \n:timeout | \n\n | Timeout in seconds (max: 600, default: 5) | \n
| Tag | \nDescription | \n
|---|---|
result | \nResult of the script evaluation | \n
exit | \nNumeric Exit-Code of the operation, 0 = success, 1 = failure | \n
You can use this functionality to write multiple return values as values into a variable by simply splitting your output.
\nFor example: You return a list of filenames as single lines that is stored in the variable \"result\":
\n/opt/myfiles/abc.txt\n/opt/myfiles/def.txt\n/opt/myfiles/hij.txtYou would then split this output using the \"newline separator\" (\\n)\nwith the following JavaScript snippet:
result: LOCAL::OutputVariable = javascript(\"${result}.split('\\n')\")This will split the contents of result after each \"newline\"-character\n(\\n) and save it into separate values of \"OutputVariable\". You would\nthen see something like this in your Issue:
\"/OutputVariable\": [\"/opt/myfiles/abc.txt\", \"/opt/myfiles/def.txt\", \"/opt/myfiles/hij.txt\"]You can use CSV input by using \"${result}\".split(\",\") in your call in\na similar way.
If you require multiple return values, these can be encoded in a simple\nJSON map and afterwards be accessed by the JSON map accessor from a\nVarString:
\nresult: OutputVariable = javascript('\n var result = {};\n result[\"ValueOne\"] = new Date;\n result[\"ValueTwo\"] = \"this is just some string\";\n JSON.stringify(result);\n')This way you end up with a JSON object looking like this:
\n {\"ValueOne\":\"Wed Dec 09 2015 14:11:45 GMT+0100 (CET)\",\"ValueTwo\":\"this is just some string\"}Which you can then freely access by using VarString in the format ${VARIABLE#value_in_object} like in this example ${OutputVariable#ValueOne}.\nPlease note that VarString only allows accessing the object directly,\nif you have a JSON structure that contains lists or other objects as values, you need to parse the structure to be able to easily access all elements.
If you wish to set Values and their respective keys at the same time you need to directly map them. To do so you will use a JavaScript call to\nset a list of \"Key:Value\" pairs which then are stored as separate entries in a variable.
\nHere we store two values with different keys to the variable SampleMap.
result: SampleMap = javascript('\n var result = {};\n result[\"SomeKey\"] = \"SomeValue\"\n result[\"2ndKey\"] = \"OtherValue\"\n result\n')Note that we did not use a JSON.stringify() this time but actually return the map directly. This will create a data structure consisting of the specified variable containing \"Key:Value\" pairs as individual values and will look like this in the Issue:
\n{\n \"/SampleMap\": [\n {\n \"value\": \"SomeValue\",\n \"key\": \"SomeKey\"\n },\n {\n \"value\": \"OtherValue\",\n \"key\": \"2ndKey\"\n }\n ]\n}| \n\n | \n\n\"Escaped characters\" The JavaScript handling for Bardioc automatically escapes special characters for Variables.\nThis means JSON data in a variable will be \"invalid\" because of the escaped quotes (\") to use JSON data stored this way you must use ''JSON.parse()''\nto read the Variable and transform it back to \"proper\" JSON.\n | \n
Here we have a simplified version of a Zendesk ticket in JSON (retrieved via API).\nWe want to extract the description and store it in a variable to react further.
\n{\n \"ticket\": {\n \"url\": \"https://itautopilot.zendesk.com/api/v2/tickets/2289.json\",\n \"id\": 2289,\n \"external_id\": null,\n \"via\": {\n \"channel\": \"web\",\n \"source\": {\n \"from\": {},\n \"to\": {},\n \"rel\": null\n }\n },\n \"created_at\": \"2016-01-14T13:19:35Z\",\n \"updated_at\": \"2016-01-14T14:03:34Z\",\n \"type\": null,\n \"subject\": \"Test Ticket - Please ignore and don't close\",\n \"raw_subject\": \"Test Ticket - Please ignore and don't close\",\n \"description\": \"Just testing some stuff.\",\n }\n}We have already retrieved the JSON data and stored it in a variable ZendeskTicketJSON.\nWe then parse the Variable into an object called obj. Then we access the value in the JSON structure.
const obj = JSON.parse('${ZendeskTicketJSON}');\nobj.ticket.descriptionThis will return the value of \"description\" as a string and store it to\nthe specified \"StoreTo\" Variable.
\n| \n\n | \n\n \n \nBardioc uses Javascript ES 2019. Make sure the elements you are trying to use are compatible with this script version. \n | \n
This can by used to extract part of a string containing an HTML/XML structure using a CSS query.
\nresult: LOCAL::RESULT = html_extract(html: \"<html text>\", css_query: \"<query string>\", [attribute: \"<attribute_name>\"])| Position | \nKeyword | \nRequired | \nDescription | \n
|---|---|---|---|
1 | \nhtml | \nX | \nHTML onto which the CSS query is applied | \n
2 | \ncss_query | \nX | \nCSS Query to perform on the HTML. e.g. \"a\" | \n
3 | \nattribute | \n\n | Optional name of an attribute to extract or \"text\" for the content | \n
| Tag | \nDescription | \n
|---|---|
result | \nArray which includes matched HTML elements or specific attribute values | \n
result: LOCAL::FULLLINK = html_extract(\"<title><a href=\\\"http://somewhere\\\">link</a></title>\", css_query: \"a\")\nresult: LOCAL::LINKTITLE = html_extract(\"<title><a href=\\\"http://somewhere\\\">link</a></title>\", css_query: \"a\", attribute: \"text\")\nresult: LOCAL::LINKURL = html_extract(\"<title><a href=\\\"http://somewhere\\\">link</a></title>\", css_query: \"a\", attribute: \"href\")In this example we match extract the following variables from the HTML snippet:
\nVariable | \nValue | \n
FULLLINK | \n<a href=\"http://somewhere\">link</a> | \n
LINKTITLE | \nlink | \n
LINKURL | \n\n |
LOCAL::HTMLCONTENT = \"\n<!DOCTYPE html>\n<html lang='en'>\n<head>\n <title>HTML EXAMPLE</title>\n <meta name='description' content='This is a description'>\n</head>\n<body>\n <h1>How to extract HTML</h1>\n <p>Please refer to the following instructions:</p>\n</body>\n\"\n\nresult: LOCAL::TITLE = html_extract(LOCAL::HTMLCONTENT, css_query: \"title\", attribute: \"text\")\nlog(LOCAL::TITLE)\nresult: LOCAL::HEADER = html_extract(LOCAL::HTMLCONTENT, css_query: \"h1\", attribute: \"text\")\nlog(LOCAL::HEADER)\nresult: LOCAL::PARAGRAPH = html_extract(LOCAL::HTMLCONTENT, css_query: \"p\", attribute: \"text\")\nlog(LOCAL::PARAGRAPH)This will yield the following results:\nLOCAL::TITLE = \"HTML EXAMPLE\"\nLOCAL::HEADER = \"How to extract HTML\"\nLOCAL::PARAGRAPH = \"Please refer to the following instructions:\"
Perform a query to retrieve data from Bardioc Graph.
\nThe applicability of this command is limited by the privileges granted to the Bardioc instance\nwhich is used to run it.
\nexit: LOCAL::EXIT,\noutput: LOCAL::OUTPUT = query(<type>, <query>, limit: <limit>, offset: <offset>, fields: <ids>, timeout: <timeout>, each: begin\n ... do something\nend)| Position | \nKeyword | \nRequired | \nDescription | \n
|---|---|---|---|
1 | \n\n | X | \nThe type of the query to perform (\"gremlin\", \"vertices\" or \"semantic\") | \n
2 | \n\n | X | \nThe query string itself | \n
| \n | root | \n\n | Root vertex to start a gremlin query from | \n
| \n | limit | \n\n | Limit the number of returned entries to this value (defaults to 20) | \n
| \n | fields | \n\n | Include these fields in the query result (defaults to all) | \n
| \n | offset | \n\n | Start from this value (defaults to 0) | \n
| \n | timeout | \n\n | Timeout for this query in ms (defaults to global engine query timeout of 120000ms) | \n
| \n | each | \n\n | Execute the KI statements between | \n
| Tag | \nDescription | \n
|---|---|
output | \nBardioc Graph result from the operation | \n
exit | \nResult code of the Bardioc Graph operation, 0 on success, 1 otherwise | \n
You can find more information on how to use the query types here:
\n| Query Type | \nDescription | \n
|---|---|
Gremlin | \n\n |
Elasticsearch (Vertices) | \n\n |
| \n\n | \n\n \n \nBoolean operators ( | \n
output: AllIssues = query(\n \"vertices\",\n 'ogit\\/_type:ogit\\/Automation\\/AutomationIssue AND ogit\\/_created-on:[now-24h TO *]',\n limit: \"-1\",\n fields: \"ogit/_id\"\n)This query will yield the ogit/_ids of all AutomationIssues (tasks) that have been created in the last 24 hours.\nTo ensure that all results are returned, the limit is set to -1.
LOCAL::NODEID = \"\"\n output: LOCAL::OUTPUT = query('vertices', 'ogit\\/_type:ogit\\/MARS\\/Machine ',\n fields: \"ogit/_id\",\n each: begin\n LOCAL::NODEID = \"${ogit/_id}\"\n log(LOCAL::NODEID)\n end\n)LOCAL:NODEID will contains the list of found ogit/_ids that are type MARS/Machine.
exit: LOCAL::EXIT, output: LOCAL::IDs = query('gremlin',\n 'out(\"ogit/dependsOn\").and(has(\"ogit/_type\",\"ogit/MARS/Machine\"),has(\"/active\",\"true\"))',\n root: known_vertex_id\n fields: \"ogit/_xid, ogit/_id, ogit/name\",\n each: begin\n add(MachineList = ogit/name)\n end\n)This query will yield all nodes of type ogit/MARS/Machine connected to the vertex with the id \"known_vertex_id\"\nwith attribute active == true.\nThe name of each result is also added to the MachineList.\n(Please note that the attribute MachineList must already be initialized for this syntax to work properly)
Read a vertex from Bardioc Graph. This function will display all the node´s attributes and their values.
\nThe applicability of this command is limited by the privileges granted to the Bardioc instance\nwhich is used to run it.
\nexit: LOCAL::EXIT,\noutput: LOCAL::OUTPUT = read_vertex(id: <vertexid>)| Position | \nKeyword | \nRequired | \nDescription | \n
|---|---|---|---|
1 | \nid | \nX | \nThe ID of the Bardioc Graph vertex to be read | \n
| Tag | \nDescription | \n
|---|---|
output | \nBardioc Graph JSON map result from the operation | \n
exit | \nResult code of the Bardioc Graph operation, 0 on success, 1 otherwise | \n
exit: LOCAL::EXIT,\noutput: LOCAL::OUTPUT = read_vertex(id: \"cln8tg3pa0fpl01868wmrpcjl_xxxxxxxxxxxxxxxxxxxxxxxx\")Read an attachment from Bardioc Graph. This function will retrieve the actual content of the attachment and should be used only on test based attachments.\nThis function is applicable only to Attachment-type Nodes. Currently, it can read only text files (txt, csv, html).
\nThe applicability of this command is limited by the privileges granted to the Bardioc instance which is used to run it.
\nexit: LOCAL::EXIT,\noutput: LOCAL::OUTPUT = read_attachment(id: <vertexid>)| Position | \nKeyword | \nRequired | \nDescription | \n
|---|---|---|---|
1 | \nid | \nX | \nThe ID of the Bardioc Graph attachment vertex to be read (referred to an attachment type Node) | \n
| Tag | \nDescription | \n
|---|---|
output | \nBardioc Graph raw content of the attachment vertex | \n
exit | \nResult code of the Bardioc Graph operation, 0 on success, 1 otherwise | \n
exit: LOCAL::EXIT,\noutput: LOCAL::OUTPUT = read_attachment(id: \"cln8tg3pa0fpl01868wmrpcjl_xxxxxxxxxxxxxxxxxxxxxxxx\")This can by used to extract part(s) of a string using a regular expression.
\n| \n\n | \n\nThe internal Elixir regex library is used, which is based on PCRE (Perl Compatible Regular Expressions).\nPlease refer to the Elixir documentation for further details.\n | \n
| \n\n | \n\nIf the string is already being matched in an on or when section, a named capture in that match is usually the better choice. It avoids writing the pattern twice and can extract several submatches at once. See Named captures.\n | \n
result: LOCAL::RESULT = regex(\"<text to be matched>\", expression: \"<regex expression>\")| Position | \nKeyword | \nRequired | \nDescription | \n
|---|---|---|---|
1 | \nstring | \nX | \nString onto which the regex is applied | \n
2 | \nexpression | \nX | \nRegular Expression, needs at least one SubMatch-Pattern. e.g. \"Value: (0-9+) Seconds\" | \n
3 | \noptions | \n\n | Modifiers for creating the Regex, e.g. \"i\". A full list of modifiers is available in the Elixir documentation. | \n
| Tag | \nDescription | \n
|---|---|
result | \nExtracted substring | \n
resultN | \nNth extracted substring (optional depending on regex) | \n
result: LOCAL::RESULT = regex(\"Here is a hidden value 47.11 inside\", expression: \".*value ([0-9.]+) .*\")In this example we match a \"string\" that contains: \"Here is a hidden\nvalue 47.11 inside\". We want to extract the number value from this so\nour regex matches only numbers with a decimal point.
\nThe resulting match of the regex is \"47.11\". This value is then stored\nin the variable RESULT in the LOCAL scope.
result: LOCAL::RESULT = regex(\"${-message}\", expression: \".*value .*\")In this example, the \"-\" character is a string modifier that converts the entire string to lowercase.\nFor more string modifiers go here\n.
\nresult: LOCAL::MAJOR, result2: LOCAL::MINOR, result3: LOCAL::PATCH = regex(\"Version 4.7.0\", \"([0-9]+)\\.([0-9]+)\\.([0-9]+)\")In this example, a version number is extracted with a multi-submatch regex, so major, minor and patch numbers are extracted separately.
\nIn order to perform case-insensitive matching, you can either use the options argument or a regex literal with options:
\n# Using options argument\nresult: LOCAL::RESULT = regex(\"VaLuE: 42.0\", expression: \"value ([0-9.]+)\", options: \"i\")\n# Using regex literal\nresult: LOCAL::RESULT = regex(\"VaLuE: 42.0\", expression: /value ([0-9.]+)/i)\n\n# The options argument does not override the options of a regex\n# literal, so this is has the same result as the last line:\nresult: LOCAL::RESULT = regex(\"VaLuE: 42.0\", expression: /value ([0-9.]+)/i, options: \"\")Read a list of values from a given timeseries and perform actions on each of them.
\nThere are two types of timeseries used by the engine: \"History\" and \"Minimal History\"(a trimmed version of History used to restore correct state of a task). These should not be modified, though they can be read.
\nThe applicability of this command is limited by the privileges granted to the Bardioc instance\nwhich is used to run it.
\nexit: LOCAL::EXIT,\noutput: LOCAL::OUTPUT = read_timeseries(<id of the timeseries>, from: <intervalstart>, to: <intervalend>, each: <code to execute>)| Position | \nKeyword | \nRequired | \nDescription | \n
|---|---|---|---|
1 | \nid | \nX | \nID of the timeseries to read values from. | \n
| \n | from | \n\n | Start of the interval to read in ms since epoch, default is 24h ago. | \n
| \n | to | \n\n | Start of the interval to read in ms since epoch, default is current system time. | \n
| \n | each | \n\n | Commands to be executed for each entry, actual values can be accessed as \"timestamp\" and \"value\". | \n
| Tag | \nDescription | \n
|---|---|
exit | \nResult code of the Bardioc Graph operation, 0 on success, 1 otherwise | \n
output | \nkey-value list of timestamps and their corresponding values | \n
| \n\n | \n\nFirst, execute find_timeseries to obtain the timeseries ID.\n | \n
LOCAL::SUM = 0\nexit: ExitCode = read_timeseries(TS_ID, each: begin SUM = SUM + value end)\nlog(\"sum of values from the last 24h: ${SUM}\")exit: LOCAL::EXIT,\noutput: TS_list = read_timeseries(TS_ID)This will result in a list like this:
\n{\"1722504885998\":\"27\",
\n\"1722504886002\":\"26.5\",
\n\"1722504886350\":\"26.8\"}
The current KI execution is paused for specified amount of time before the next command will be executed.
\nsleep(time: <seconds>)| Position | \nKeyword | \nRequired | \nDescription | \n
|---|---|---|---|
1 | \ntime | \nX | \ntime in seconds the KI execution will pause | \n
sleep(time: 60)This can be used replace a substring within a string.
\nresult: LOCAL::RESULT = replace(\"<string to modify>\", \"<substring to replace>\", \"<replacement substring>\")| Position | \nRequired | \nDescription | \n
|---|---|---|
1 | \nX | \nString in which the replacement will be performed | \n
2 | \nX | \nSubstring to search for within the string | \n
3 | \nX | \nValue that will replace the matched substring | \n
| Tag | \nDescription | \n
|---|---|
result | \nString with the replaced substring | \n
result: LOCAL::RESULT = replace(\"Some text here\", \"text\", \"value\")In this example we replace a substring within a \"string\" by defining the value to be replaced and the replacement value.
\nThe original string \"Some text here\" contains the value \"text\", which will be replaced with \"value\".
\nThe resulting string will be \"Some value here\" which will be stored in the variable RESULT in the LOCAL scope.
This can by used to convert a string value to a list using a configurable separator.
\nresult: LOCAL::RESULT = split(string: \"<text to be split>\", separator: \"<separator>\")| Position | \nKeyword | \nRequired | \nDescription | \n
|---|---|---|---|
1 | \nstring | \nX | \nString to split | \n
2 | \nseparator | \nX | \nSeparator to use for splitting the string. Defaults to \" \" (whitespace) | \n
| Tag | \nDescription | \n
|---|---|
result | \nList of the extracted substrings | \n
result: LOCAL::RESULT = split(\"Some,CSV,List,Here\", \",\")In this example we split a \"string\" that contains a simple comma separated list using the comma as separator.
\nThe resulting list will contain the values \"Some\", \"CSV\", \"List\" and \"Here\" which will be stored\nin the variable RESULT in the LOCAL scope.
The current or given issue is \"stopped\", removed from engine processing and set into STOPPED state.
\nstop_issue(message: <stop message>, issue_id: <issue_id>)| Position | \nKeyword | \nRequired | \nDescription | \n
|---|---|---|---|
1 | \nmessage | \n\n | Message to be set as stop reason for deployStatus, defaults to \"stopped by KI $KIID\" | \n
2 | \nissue_id | \n\n | ID of the Issue to be stopped, by default the current one is used | \n
stop_issue(message: \"ExecIdle threshold (${ogit/Automation/maxIdleTime})\")The current Issue is \"suspended\" from engine processing for a specified amount of time but will remain in PROCESSING state.
\n| \n\n | \n\nThe suspend command is always executed last. The current KI block will continue to run and complete all remaining commands before the suspend takes effect. The specified suspend duration begins only after the current KI execution has finished.\n | \n
suspend(time: <seconds>)| Position | \nKeyword | \nRequired | \nDescription | \n
|---|---|---|---|
1 | \ntime | \nX | \ntime in seconds the issue processing should be suspended | \n
suspend(time: \"60\")Update a vertex in Bardioc Graph. This allows adding, changing or removing\nattributes from Bardioc Graph data vertices.
\nThe applicability of this command is limited by the privileges granted to the Bardioc instance\nwhich is used to run it.
\nTo add or update attributes, simply use \"Name:Value\" pairs.
\nTo remove an attribute from the vertex you need to supply the attribute name and value nil. See example below.
exit: LOCAL::EXIT,\noutput: LOCAL::OUTPUT = update_vertex(id: <id>, attributes: [<key1>: <value1>, <key2>: <value2>, ...])| Position | \nKeyword | \nRequired | \nDescription | \n
|---|---|---|---|
1 | \nid | \nX | \nThe ID of the Bardioc Graph vertex to be updated | \n
| \n | attributes | \n\n | List of attributes to be updated at the vertex. An entry is in the format | \n
| Tag | \nDescription | \n
|---|---|
output | \nBardioc Graph result from the operation | \n
exit | \nResult code of the Bardioc Graph operation, 0 on success, 1 otherwise | \n
exit: LOCAL::EXIT,\noutput: LOCAL::OUTPUT = update_vertex(id: \"cln8tg3pa0fpl01868wmrpcjl_xxxxxxxxxxxxxxxxxxxxxxxx\", attributes: [\"UpdatedBy\":\"MB\"])exit: LOCAL::EXIT,\noutput: LOCAL::OUTPUT = update_vertex(id: \"cln8tg3pa0fpl01868wmrpcjl_xxxxxxxxxxxxxxxxxxxxxxxx\", attributes: [\"-/UpdatedBy\":\"\"])By using the + sign before your attribute name, you can add a value to the existing attribute as a json object within an array.
exit: LOCAL::EXIT,\noutput: LOCAL::OUTPUT = update_vertex(id: \"cln8tg3pa0fpl01868wmrpcjl_xxxxxxxxxxxxxxxxxxxxxxxx\", attributes: [\"+/UpdatedBy\":\"\"])This will result in an array of json objects
\n\"/UpdatedBy\": [
\n {
\n \"created\": xxxxxxxxxxx,
\n \"value\": \"person1\"
\n },
\n {
\n \"created\": xxxxxxxxxxx,
\n \"value\": \"person2\"
\n }
\n]
The current Issue is \"suspended\" from engine processing until a fixed point in time but will remain in PROCESSING state.
\n| \n\n | \n\nThe suspend_until command is always executed last. The current KI block will continue to run and complete all remaining commands before the suspend takes effect. The issue is suspended only after the current KI execution has finished.\n | \n
suspend_until(\"<utc8601-timestamp>\")| Position | \nKeyword | \nRequired | \nDescription | \n
|---|---|---|---|
1 | \n\n | X | \ntimestamp in UTC8601 when issue processing will be resumed. Format: YYYY-MM-DDTHH:MM:SSZ , where Z designates the timezone UTC. | \n
suspend_until(\"2022-01-25T11:07:00+01:00\")Update the content of an attachment vertex in Bardioc Graph.
\n| \n\n | \n\n \n \n
| \n
The applicability of this command is limited by the privileges granted to the Bardioc instance which is used to run it.
\n| \n\n | \n\nIf Attachment Node does not exist, you can create it with function create_vertex . You might want to do the connection between Nodes with connect. Here you can find the definition for the attachment Nodes as well as the possible connection to other Nodes types.\n | \n
exit: LOCAL::EXIT,\noutput: LOCAL::OUTPUT = write_attachment(id: <id>, content: <content>)| Position | \nKeyword | \nRequired | \nDescription | \n
|---|---|---|---|
1 | \nid | \nX | \nThe ID of the Bardioc Graph vertex to be updated (attachment type Node) | \n
2 | \ncontent | \nX | \nString content to be written as content of the attachment vertex | \n
| Tag | \nDescription | \n
|---|---|
error | \nBardioc Graph result from the operation if not successful | \n
exit | \nResult code of the Bardioc Graph operation, 0 on success, 1 otherwise | \n
exit: LOCAL::EXIT,\nerror: LOCAL::ERROR = write_attachment(id: \"cln8tg3pa0fpl01868wmrpcjl_xxxxxxxxxxxxxxxxxxxxxxxx\", content: \"Hello World\")Write a value to a given timeseries.
\nIt will create a series of timestamps with their corresponding values. The content will always be referred to as \"value\" and is subject to user interpretation, whether it represents an error, data point, operating system or other information.
\nRemember there are two types of timeseries used by the engine: \"History\" and \"Minimal History\".These should not be modified, though they can be read.
\nThe applicability of this command is limited by the privileges granted to the Bardioc instance\nwhich is used to run it.
\nexit: LOCAL::EXIT,\noutput: LOCAL::OUTPUT = write_timeseries(<id of the timeseries>, value: <value> , [timestamp: <timestamp>])| Position | \nKeyword | \nRequired | \nDescription | \n
|---|---|---|---|
1 | \nid | \nX | \nID of the timeseries to write the value to. | \n
2 | \nvalue | \nX | \nThe value to be written to the timeseries. | \n
| \n | timestamp | \n\n | Optional timestamp in ms since epoch for the value to be written, default is current system time. | \n
| Tag | \nDescription | \n
|---|---|
exit | \nResult code of the Bardioc Graph operation, 0 on success, 1 otherwise | \n
| \n\n | \n\nFirst, execute find_timeseries to obtain the timeseries ID.\n | \n
exit: LOCAL::EXIT,\noutput: LOCAL::OUTPUT = write_timeseries(id:TS_ID, value : \"${temperature_now}\")Each time this KI is executed, it will store a temperature value at the specified timestamp.\nThis will generate a list like the following:
\n{\"1722504885998\":\"27\",
\n\"1722504886002\":\"26.5\",
\n\"1722504886350\":\"26.8\"}