Documentation
Table of Contents
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 (Host navigator with its Reference parameter set to "ABCDE") as the data source containing the host.DASHBOARD._hostid - set the dashboard Host selector as the data source containing the host.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 (Graph, Graph (classic) or Graph prototype with its Reference parameter set to "ABCDE") as the data source.Default: DASHBOARD._timeperiodAlternatively, 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.
{
"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: