Operators

Operators can be used to normalize a value which was retrieved from a device. They are always given in form of an array. This means there are multiple operators which are executed after each other. The first element of the operator array receives a value and executes an operation on it, for example modifies it. Then the modified value is passed to the next operator in the array. This goes on until there are no operators left, or an error occurs. That way a read out value can be changed multiple times by different operators, before it is finally normalized and will be returned.

There are three different operator types: filter, switch and modify. These types again have various methods, that define how a value is filtered, switched or modified. Depending on what type and what method is used for an operator, there are different parameters which need to be set.

Filter

The filter operator has the following structure:

parameter Description
filter_method method used to filter a result
value comparison value when filtering
return_on_mismatch boolean that indicates if value is returned also when the filter fails

Filter operators can be compared to conditions. The main difference is that a filter operator does not read out any value, as it receives a value that was already read out before. The filter_method is identical to the match_mode parameter of a condition and defines how the filter compares the value it receives with the given comparison value defined in the value parameter.

Only if the the filter returns true, the value will be passed to the next operator or returned. This way various conditions can be defined that must apply to a value that is read out. If the value does not meet these conditions, it will not be accepted.

Filters can also be used to modify a value under certain conditions. The return_on_mismatch parameter defines if a value is still returned if the filter does not match. When this parameter is true and a filter does not match for the current value, this value will still be accepted and returned. This allows performing some additional operators on a value if it meets certain conditions. If these conditions are not met, the value will still be accepted.

The following example shows a filter operator which makes use of this:

- type: filter
  filter_method: startsWith
  value: "IP-20"
  return_on_mismatch: true
- type: modify
  ...

If the current value starts with “IP-20”, this filter will return true and the value with be modified with the next operator. If the filter does not match, the value will just be returned.

Switch

A switch operator is a special form of a filter operator. It allows multiple cases depending on what filter matches for the given value.

The switch operator has the following structure:

parameter Description
switch_method method used to switch a value
cases list / array of switch cases

Such a switch case always has two parameters: case and operators. case is identical to the value parameter of a filter operator and defines if a value will be assigned to that case. operators is a list of additional operators which will only be used in that particular case.

The following example shows a switch operator, which will overwrite a value to 1 if it is 0 and to 0 if it is not 0:

type: switch
switch_mode: regex
cases:
    - case: "0"
      operators:
        - type: modify
          modify_method: overwrite
          value: "1"
    - case: ".*"
      operators:
        - type: modify
          modify_method: overwrite
          value: "0"

Modify

The last operator type is called modify and is used to modify a value. It has the following base structure:

parameter Description
modify_method method used to modify a value

For this operator the modify_method defines which additional parameters need to be set.

There are the following modify methods available:

modify_method Parameters Description
regexReplace
  • regex (string)
  • replace (string)
  • replace sub strings with help of a regex
    regexSubmatch
  • regex (string)
  • format (string)
  • cut out sub strings with a regex and a format
    toUpperCase / change all letters to upper case
    toLowerCase / change all letters to lower case
    addPrefix
  • value (string)
  • add a prefix
    addSuffix
  • value (string)
  • add a suffix
    multiply
  • value (property reader)
  • multipy value with another one
    divide
  • value (property reader)
  • divide value by another one
    map
  • ignore_on_mismatch (boolean, optional)
  • mappings (key (string) + value (string))
  • 1 to 1 mapping from original value to a new one
    insertReadValue
  • read value (property reader)
  • format (string)
  • read out other value and put it together with the current value

    The following example shows a modify operator that multiplies a value by 1000:

    type: modify
    modify_method: multiply
    value:
        detection: constant
        value: 1000