- 02 May 2024
-
DarkLight
-
PDF
Defining Command Templates
- Updated on 02 May 2024
-
DarkLight
-
PDF
Command Templates contain sets of commands with associated rules, including flags to define rules logic.
Global Command Pass
At the top of the template is a dropdown menu (All Commands must pass/ One Command must pass) that works the same as setting the individual pass flags on each command, except on a global level.
- All commands must pass (default behavior): Pass for every rule in every command.
- All commands must pass (warn/info as pass checked): Zero errors errors present in the template.
- One command must pass (default behavior): Pass for all rules in ONE (or more) commands.
- One command must pass (warn/info as pass checked): One command with zero errors must be present in the template.
There is also a pass checkbox (optional) to ignore failures due to warning or info severity levels. The default for the global pass checkbox is "off'.
Rules
The following options are available in the Rules dropdown for all Command Templates. For more information, see the sections on Command Template Variables and Defining Command Template Rules below.
Option | Description |
---|---|
contains |
Will verify a specified string exists in the device response. |
!contains |
Will verify a specified string does not exist in the device response. |
contains1 |
Will verify a specified string exists only once in the device response. |
RegEx |
Will verify a regular expression matches the device response. |
!RegEx |
Will verify a regular expression does not match the device response. |
#comparison |
Compares two values, both of which may be extracted from the device response. |
Flags
Every command may have one or more rules which are bound by a boolean Flag called a "pass flag".
- When a pass flag is set to
true
(on), the logic between the rules is "AND". This means all rules must pass in order for the command to pass. - When a pass flag is set to
false
(off), the logic is "OR". This means that only one rule has to pass for the command to pass.
The following flags are supported.
Flag | Description |
---|---|
i |
Ignore case. Make the whole expression case-insensitive. |
g |
Global search. Retain the index of the last match, allowing iterative searches. |
m |
Multi-line. Beginning/end anchors (^ /$ ) will match the start/end of a line. |
Of note, the contains
option only has one flag option: i
.
The RegEx
and comparison
options have all three flag options: i
, g
, and m
.
Severity
A Severity field is available for each rule. The severity only applies to a rule after it has failed. The default severity is error
.
Level | Description |
---|---|
error | Something is wrong or is not behaving normally, and a specific action may need to be taken. |
warning | There is something to be aware of that could potentially cause a problem. |
info | Informational messages have been logged. |
Global Rules Pass
For each command there is a dropdown (All Rules must pass/ One Rule must pass) that works the same as setting rules on each command, except on a global level.
- All Rules must pass: Pass for every rule in a command.
- One Rule must pass: Pass for one rule (or more) in a command.
Command Template Variables
When defining Command Templates, variables may be used in the commands with the following syntax:
<!VARIABLE!>
The following variable types can be used when defining commands:
- string
- number
- boolean
- array of strings
- array of numbers
- array of booleans
When arrays of simple types are passed into the execution engine, the command will be executed one time for each element in the array. Complex variable structures such as arrays of complex objects are not currently supported.
Defining Command Template Rules
The contains
and RegEx
operators search for command output matching (or not matching) a given string or regular expression. The #comparison
operator evaluates the values in returned data.
Rule Type | Match Type to Device Response | Output | Supported Flag |
---|---|---|---|
contains |
String | True if the device response contains the requested value. | Ignore case (i) |
!contains |
String | True if the device response does not contain the requested value. | Ignore case (i) |
contains1 |
String | True if the device response contains 1 and only 1 occurence of the requested value. | Ignore case (i) |
RegEx |
Regular expression comparison. | True if the device response matches the requested regex pattern. | Ignore case (i) Global search (g) Multi-line (m) |
#comparison |
Comparison against two values, both of which may be extracted from the device response. | The #comparison rule type defines its own set of Operands (Top and Bottom) and a Comparison Operator. See below for more information. |
Top Comparison Operands
- Uses a regular expression with a capture group to select data in the output of a command. The regular expression must be surrounded with slash (/) characters.
- The expression serves two functions: it identifies the command output location (where we will find the top comparison operand value) and returns the comparison operand value.
- Capture groups are created by surrounding the relevant part of the regular expression with round brackets or parentheses. A single capture group is supported.
Bottom Comparison Operands
- Will specify a static value, a passed MOP command template variable, or a second regular expression and capture group matching part of the command's output.
Comparison Operators
Comparison operators compare values and return true or false.
Operator | Comparison Type | Description |
---|---|---|
= | String | Returns true if the top and bottom string comparison operands are equal; otherwise returns false. |
!= | String | Returns true if the top and bottom string comparison operands are not equal; otherwise returns false. |
<= | Number | Returns true if the top number comparison operand is equal to or less than the bottom number comparison operand; otherwise returns false. |
< | Number | Returns true if the top number comparison operand is less than the bottom number comparison operand; otherwise returns false. |
>= | Number | Performs a number comparison. Returns true if the top number comparison operand is greater than or equal to the bottom number comparison operand; otherwise returns false. |
> | Number | Returns true if the top number comparison operand is greater than the bottom number comparison operand; otherwise returns false. |
% | Number | Evaluates a percentage value calculation against a threshold. The percentage value is calculated by multiplying 100 times the bottom number comparison operand divided by the top number comparison operand: 100 x (bottom comparison operand / top comparison operand) . The threshold is a static number typed in the Max accepted % field. Returns true if the percentage value is less than or equal to the threshold; otherwise it returns false. |