Custom columns language reference

Introduction

The list views enables the user to create quite advanced custom columns for each table. To do so, a custom column language needs to be used.

For real world examples, and where to use the language, see Customizing Listview Columns.

For advanced users who want to read the low level grammar definition, it can be found visualized in your monitor system, on the page: (update the hostname to your system)

http://my.monitor.server.example.org/monitor/modules/lsfilter/html/LSColumnsVisualization.html

Define a list of columns

The table definition is a list of column instructions which separated by a comma:

<column>, <column>, <column> ...

The <column> can be any of the following:

  • (6.1) A name of a predefined column. These names is table-dependent, and a list of the column names can be found here: (FIXME)
  • (6.1) A removal of a column, put a minus sign before the name. For example, -description (for services).
  • (6.2) The magic word default, which represents all columns defined by the system administrator. The all and default are in the default configuration the same. In 6.1, default was available as alias for all, and is preferred to use to simplify the upgrade.
  • (6.1) The magic word all, which represents all non-custom columns defined by the system.
  • (6.1) A custom column definition, containing a name (as a quoted string), an equal sign (=), and a column definition.

Example (for services):

status_information, default, -attempt, "Custom column" = 13
Custom column definition 

(Introduced in 6.1)

The custom column definition is the result of an expression. The expression results a value, of type, either string, number, boolean or list.

The expression can be any of the following:

  • (6.1) Operators, like expr = expr + expr
  • (6.1) A object field name, referring to the object of the table, like "name", for hosts, or "host.name" or "description" for services
  • (6.2) A function call, example: time(next_check)
  • (6.2) If statement
  • (6.2) A list comprehension
  • (6.2) An element in a list, example: services_with_info[0]

Operators

(Introduced in 6.1)

There are several binary operators for use in the expression. Those operators have precedence, so lower priority is evaluated after.

The Available operators are:

Operator Example Description Priority Available since
Equality a = b Compares the values, true if a equals b 1 6.1
Add a + b Computes sum of a and b 2 6.1
Subtract a - b Computes difference of a and b 2 6.1
Multiplication a * b Computes the product of a and b 3 6.1
Division a / b Computes the fraction of a and b 3 6.1
Negation - a Changes sign of a, example 3 becomes -3 4 6.1
Parenthesis ( a ) Makes a be evaluated before, independent of priority high 6.1

Object field name

(Introduced in 6.1)

To access information of the objects, there are several variables defined for the object. Which variables are available is dependent on which table the column is defined for.

Several tables have objects referring to objects in other tables, which is available under the prefix of the object name. For example, services can access parameters for the host. The host field "name" is for the service available as "host.name".

Example (for services):

"Identifier" = host.name + ";" + description

The fields available is the fields available for filters, see Listview Filter Columns. There are a few extra fields in 6.2 (To be documented).

Function calls

(Introduced in 6.2)

To manipulate and format data, some function calls can be useful. A function call is written like:

functionname(arg, arg, arg, ...)

Functions available are:

Function Description Available since
implode( separator, list )
Join each element in the list to a string, with the separator as separator 6.2
time( unixtimestamp )
Convert a unix timestamp to a human readable time. Many column in the system returns a timestamp, which needs to be processed with this to be readable 6.2
idx( id, val0, val1, val2, ... )
Return the value of one argument, given the value of id. Useful for setting names on, for example, states. Example: idx( state, "Ok", "Warning", "Critical", "Unknown" ) 6.2
urlencode( string )
Escape a string to be used as an attribute in an url. Useful when building links. 6.2
htmlescape( string )
Escape a string to be visible on the page. Useful for example for plugin output to be visible without interfering with the rest of the custom column style. 6.2
link( relative_url, contant )
Build a link to an internal page on monitor. The relative_url is relative to http://monitor.example.org/monitor/index.php/. Example: link( "extinfo/host?host=" + urlencode(host.name), "Host extinfo" ) 6.2
nl2br( string )
Convert newlines to linebreaks. This is useful to format the long plugin output as a custom column. nl2br( htmlescape( plugin_output + "\n" + long_plugin_output ) ) 6.2

Grammar

For a person want to read the low level definition of the grammar, in OP5 Monitor 6.2:

expr4     = name '(' expr_list ')'
expr_list = expr ',' expr_list
expr_list = expr

If statement

(Introduced in 6.2)

To select either one expression or the other, given a criteria, an if statement can be used. The syntax is:

if test-expression then expression-if-true else expression-if-false

Example:

"has been checked" = if has_been_checked then "yes" else "no"

List comprehension

(Introduced in 6.2)

To apply an expression on each element in a list, a list comprehension can be used. The syntax is as follows:

[ for-every-element-expression for variable in list-expression ]

The for-every-element-expression is applied on every element in the list represented by list-expression. The variable specified in variable is set to the element in list-expression.

Example, for hosts, which creates a link to each service extinfo for a host (in the hosts-table):

[ link( "/extinfo/details?host=" + urlencode(name) + "&service=" + urlencode(svc), htmlescape(svc) ) for svc in services ]

In this case, name comes from the host, which also contains the field services. The list comprehension provides the svc-variable (as "for svc" is written) in the first expression generating the link.

In a list comprehension, a filter can be applied, to only return some values. In that case, add an if statement, where the corresponding expression returns a true, the item in the list is processed. Written as:

for-every-element-expression for variable in list-expression if filter-expression ]

In the previous example, only output services named "PING". For more examples, see Customizing Listview Columns.

[ link( "/extinfo/details?host=" + urlencode(name) + "&service=" + urlencode(svc), htmlescape(svc) ) for svc in services if svc = "PING" ]

Element of a list

(Introduced in 6.2)

To access an indexed element in a list, add [ id ] to the list. Only integer values can be used for now, not an entire expression. The first attribute needs to be a variable, not an expression.

Example:

"First service" = services[0]

This is mostly useful in combination with the host field "services_with_info" and a list comprehension. See examples in Customizing Listview Columns.