15 Item history

Description

These parameters and the possible property values for the respective dashboard widget field objects allow to configure the Item history widget in dashboard.create and dashboard.update methods.

Widget fields properties are not validated during the creation or update of a dashboard. This allows users to modify built-in widgets and create custom widgets, but also introduces the risk of creating or updating widgets incorrectly. To ensure the successful creation or update of the Item history widget, please refer to the parameter behavior outlined in the tables below.

Parameters

The following parameters are supported for the Item history widget.

Parameter type name value
Refresh interval 0 rf_rate 0 - No refresh;
10 - 10 seconds;
30 - 30 seconds;
60 - (default) 1 minute;
120 - 2 minutes;
600 - 10 minutes;
900 - 15 minutes.
Layout 0 layout 0 - (default) Horizontal;
1 - Vertical.
Columns (see below)
Show lines 0 show_lines Possible values range from 1-100.

Default: 25.
Override host 1 override_hostid._reference ABCDE._hostid - set a compatible widget (with its Reference parameter set to "ABCDE") as the data source for hosts;
DASHBOARD._hostid - set the dashboard Host selector as the data source for hosts.

This parameter is not supported if configuring the widget on a template dashboard.
Advanced configuration (see below)
Reference 1 reference Any string value consisting of 5 characters (e.g., ABCDE or JBPNL). This value must be unique within the dashboard to which the widget belongs.

Parameter behavior:
- required

Columns

Columns have common parameters and additional parameters depending on the configuration of the Item parameter.

For all parameters related to columns, the number in the property name (e.g. columns.0.name) references a column for which the parameter is configured.

The following parameters are supported for all columns.

Parameter type name value
Name 1 columns.0.name Any string value.

Parameter behavior:
- required
Item 4 columns.0.itemid Item ID.

When configuring the widget on a template dashboard, only items configured on the template should be set.

Parameter behavior:
- required
Base color 1 columns.0.base_color Hexadecimal color code (e.g. FF0000).

Default: "" (empty).

The following column parameters are supported if the configured Item is a numeric type item.

Parameter type name value
Display 0 columns.0.display 1 - (default) As is;
2 - Bar;
3 - Indicators.
Min 1 columns.0.min Any numeric value.

Parameter behavior:
- supported if Display is set to "Bar" or "Indicators"
Max 1 columns.0.max Any numeric value.

Parameter behavior:
- supported if Display is set to "Bar" or "Indicators"
Thresholds
Color 1 columns.0.thresholds.0.color Hexadecimal color code (e.g. FF0000).
Threshold 1 columns.0.thresholds.0.threshold Any numeric value. Suffixes (e.g. "1d", "2w", "4K", "8G") are supported.
History data 0 columns.0.history 0 - (default) Auto;
1 - History;
2 - Trends.

The following column parameters are supported if the configured Item is a character, text, or log type item.

Parameter type name value
Highlights
Highlight 1 columns.0.highlights.0.color Hexadecimal color code (e.g. FF0000).
Threshold 1 columns.0.highlights.0.pattern Any regular expression.
Display 0 columns.0.display 1 - (default) As is;
4 - HTML;
5 - Single line.
Single line 0 columns.0.max_length Possible values range from 1-500.

Default: 100.

Parameter behavior:
- supported if Display is set to "Single line"
Use monospace font 0 columns.0.monospace_font 0 - (default) Use default font;
1 - Use monospace font.
Display local time 0 columns.0.local_time 0 - (default) Display timestamp;
1 - Display local time.

Parameter behavior:
- supported if Item is set to log type item, and Show timestamp is set to "Enabled"

The following column parameters are supported if the configured Item is a binary type item.

Parameter type name value
Show thumbnail 1 columns.0.show_thumbnail 0 - (default) Disabled;
1 - Enabled.

Advanced configuration

The following advanced configuration parameters are supported for the Item history widget.

Parameter type name value
New values 0 sortorder 0 - (default) Top;
1 - Bottom.
Show timestamp 0 show_timestamp 0 - (default) Disabled;
1 - Enabled.
Show column header 0 show_column_header 0 - Off;
1 - Horizontal;
2 - (default) Vertical.
Time period 1 time_period._reference DASHBOARD._timeperiod - set the Time period selector as the data source;
ABCDE._timeperiod - set a compatible widget (with its Reference parameter set to "ABCDE") as the data source.

Default: DASHBOARD._timeperiod

Alternatively, you can set the time period only in the From and To parameters.
From 1 time_period.from Valid time string in absolute (YYYY-MM-DD hh:mm:ss) or relative time syntax (now, now/d, now/w-1w, etc.).

Parameter behavior:
- supported if Time period is not set
To 1 time_period.to Valid time string in absolute (YYYY-MM-DD hh:mm:ss) or relative time syntax (now, now/d, now/w-1w, etc.).

Parameter behavior:
- supported if Time period is not set

Examples

The following examples aim to only describe the configuration of the dashboard widget field objects for the Item history widget. For more information on configuring a dashboard, see dashboard.create.

Configuring an Item history widget

Configure an Item history widget that displays latest data for two numeric items "42269" and "42270". In addition, configure the item columns to be displayed vertically, with column names displayed horizontally; limit the display to 15 lines of data and include a separate timestamp column.

Request:

{
           "jsonrpc": "2.0",
           "method": "dashboard.create",
           "params": {
               "name": "My dashboard",
               "display_period": 30,
               "auto_start": 1,
               "pages": [
                   {
                       "widgets": [
                           {
                               "type": "itemhistory",
                               "name": "Item history",
                               "x": "0",
                               "y": "0",
                               "width": "18",
                               "height": "6",
                               "view_mode": "0",
                               "fields": [
                                   {
                                       "type": "0",
                                       "name": "layout",
                                       "value": "1"
                                   },
                                   {
                                       "type": "1",
                                       "name": "columns.0.name",
                                       "value": "CPU utilization"
                                   },
                                   {
                                       "type": "4",
                                       "name": "columns.0.itemid",
                                       "value": "42269"
                                   },
                                   {
                                       "type": "1",
                                       "name": "columns.1.name",
                                       "value": "Memory utilization"
                                   },
                                   {
                                       "type": "4",
                                       "name": "columns.1.itemid",
                                       "value": "42270"
                                   },
                                   {
                                       "type": "0",
                                       "name": "show_lines",
                                       "value": "15"
                                   },
                                   {
                                       "type": "0",
                                       "name": "show_timestamp",
                                       "value": "1"
                                   },
                                   {
                                       "type": "0",
                                       "name": "show_column_header",
                                       "value": "1"
                                   },
                                   {
                                       "type": "1",
                                       "name": "reference",
                                       "value": "KIVKD"
                                   }
                               ]
                           }
                       ]
                   }
               ],
               "userGroups": [
                   {
                       "usrgrpid": 7,
                       "permission": 2
                   }
               ],
               "users": [
                   {
                       "userid": 1,
                       "permission": 3
                   }
               ]
           },
           "id": 1
       }

Response:

{
           "jsonrpc": "2.0",
           "result": {
               "dashboardids": [
                   "3"
               ]
           },
           "id": 1
       }

See also