17 Item value

Description

These parameters and the possible property values for the respective dashboard widget field objects allow to configure the Item value 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 value widget, please refer to the parameter behavior outlined in the tables below.

Parameters

The following parameters are supported for the Item value 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.
Item 4 itemid.0 Item ID.

Parameter behavior:
- required if Item (Widget) is not set
Item (Widget) 1 itemid._reference Instead of Item ID:
ABCDE._itemid - set a compatible widget (with its Reference parameter set to "ABCDE") as the data source for items.

Parameter behavior:
- required if Item is not set
Show 0 show.0 1 - Description;
2 - Value;
3 - Time;
4 - Change indicator;
5 - Sparkline.

Default: 1, 2, 3, 4.

Note: To configure multiple values, create a dashboard widget field object for each value with an incremented number in the property name.
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

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

The number in the Thresholds property name (e.g. thresholds.0.color) references the threshold place in a list, sorted in ascending order. However, if thresholds are configured in a different order, the values will be sorted in ascending order after updating widget configuration in Zabbix frontend (e.g. "thresholds.0.threshold":"5""thresholds.0.threshold":"1"; "thresholds.1.threshold":"1""thresholds.1.threshold": "5").

Parameter type name value
Background color 1 bg_color Hexadecimal color code (e.g. FF0000).

Default: "" (empty).
Thresholds
Color 1 thresholds.0.color Hexadecimal color code (e.g. FF0000).
Threshold 1 thresholds.0.threshold Any string value.
Aggregation function 0 aggregate_function 0 - (default) not used;
1 - min;
2 - max;
3 - avg;
4 - count;
5 - sum;
6 - first;
7 - last.
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 equal to ABCDE) as the data source.

Default: DASHBOARD._timeperiod

Alternatively, you can set the time period only in the From and To parameters.

Parameter behavior:
- supported if Aggregation function is set to "min", "max", "avg", "count", "sum", "first", "last"
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 and Aggregation function is set to "min", "max", "avg", "count", "sum", "first", "last"
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 and Aggregation function is set to "min", "max", "avg", "count", "sum", "first", "last"
History data 0 history 0 - (default) Auto;
1 - History;
2 - Trends.
Description

The following advanced configuration parameters are supported if Show is set to "Description".

Parameter type name value
Description 1 description Any string value, including macros.
Supported macros: {HOST.*}, {ITEM.*}, {INVENTORY.*}, User macros.

Default: {ITEM.NAME}.
Horizontal position 0 desc_h_pos 0 - Left;
1 - (default) Center;
2 - Right.

Two or more elements (Description, Value, Time) cannot share the same Horizontal position and Vertical position.
Vertical position 0 desc_v_pos 0 - Top;
1 - Middle;
2 - (default) Bottom.

Two or more elements (Description, Value, Time) cannot share the same Horizontal position and Vertical position.
Size 0 desc_size Possible values range from 1-100.

Default: 15.
Bold 0 desc_bold 0 - (default) Disabled;
1 - Enabled.
Color 1 desc_color Hexadecimal color code (e.g. FF0000).

Default: "" (empty).
Value

The following advanced configuration parameters are supported if Show is set to "Value".

Parameter type name value
Decimal places
Decimal places 0 decimal_places Possible values range from 1-10.

Default: 2.
Size 0 decimal_size Possible values range from 1-100.

Default: 35.
Position
Horizontal position 0 value_h_pos 0 - Left;
1 - (default) Center;
2 - Right.

Two or more elements (Description, Value, Time) cannot share the same Horizontal position and Vertical position.
Vertical position 0 value_v_pos 0 - Top;
1 - (default) Middle;
2 - Bottom.

Two or more elements (Description, Value, Time) cannot share the same Horizontal position and Vertical position.
Size 0 value_size Possible values range from 1-100.

Default: 45.
Bold 0 value_bold 0 - Disabled;
1 - (default) Enabled.
Color 1 value_color Hexadecimal color code (e.g. FF0000).

Default: "" (empty).
Units
Units (checkbox) 0 units_show 0 - Disabled;
1 - (default) Enabled.
Units (value) 1 units Any string value.
Position 0 units_pos 0 - Before value;
1 - Above value;
2 - (default) After value;
3 - Below value.
Size 0 units_size Possible values range from 1-100.

Default: 35.
Bold 0 units_bold 0 - Disabled;
1 - (default) Enabled.
Color 1 units_color Hexadecimal color code (e.g. FF0000).

Default: "" (empty).
Time

The following advanced configuration parameters are supported if Show is set to "Time".

Parameter type name value
Horizontal position 0 time_h_pos 0 - Left;
1 - (default) Center;
2 - Right.

Two or more elements (Description, Value, Time) cannot share the same Horizontal position and Vertical position.
Vertical position 0 time_v_pos 0 - (default) Top;
1 - Middle;
2 - Bottom.

Two or more elements (Description, Value, Time) cannot share the same Horizontal position and Vertical position.
Size 0 time_size Possible values range from 1-100.

Default: 15.
Bold 0 time_bold 0 - (default) Disabled;
1 - Enabled.
Color 1 time_color Hexadecimal color code (e.g. FF0000).

Default: "" (empty).
Change indicator

The following advanced configuration parameters are supported if Show is set to "Change indicator".

Parameter type name value
Change indicator ↑ color 1 up_color Hexadecimal color code (e.g. FF0000).

Default: "" (empty).
Change indicator ↓ color 1 down_color Hexadecimal color code (e.g. FF0000).

Default: "" (empty).
Change indicator ↕ color 1 updown_color Hexadecimal color code (e.g. FF0000).

Default: "" (empty).
Sparkline

The following advanced configuration parameters are supported if Show is set to "Sparkline".

Parameter type name value
Width 0 sparkline.width Possible values range from 0-10.

Default: 1.
Fill 0 sparkline.fill Possible values range from 0-10.

Default: 3.
Color 1 sparkline.color Hexadecimal color code (e.g. FF0000).

Default: 42A5F5.
Time period 1 sparkline.time_period._reference DASHBOARD._timeperiod - set the Time period selector as the data source;
ABCDE._timeperiod - set a compatible widget (with its reference parameter equal 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 sparkline.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.).
To 1 sparkline.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.).
History data 0 sparkline.history 0 - (default) Auto;
1 - History;
2 - Trends.

Examples

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

Configuring an Item value widget

Configure an Item value widget that displays the item value for the item "42266" (Zabbix agent availability). In addition, visually fine-tune the widget with multiple advanced options, including a dynamic background color that changes based on the availability status of Zabbix agent.

Request:

{
           "jsonrpc": "2.0",
           "method": "dashboard.create",
           "params": {
               "name": "My dashboard",
               "display_period": 30,
               "auto_start": 1,
               "pages": [
                   {
                       "widgets": [
                           {
                               "type": "item",
                               "name": "Item value",
                               "x": 0,
                               "y": 0,
                               "width": 12,
                               "height": 3,
                               "view_mode": 0,
                               "fields": [
                                   {
                                       "type": 4,
                                       "name": "itemid.0",
                                       "value": 42266
                                   },
                                   {
                                       "type": 0,
                                       "name": "show.0",
                                       "value": 1
                                   },
                                   {
                                       "type": 0,
                                       "name": "show.1",
                                       "value": 2
                                   },
                                   {
                                       "type": 0,
                                       "name": "show.2",
                                       "value": 3
                                   },
                                   {
                                       "type": 1,
                                       "name": "description",
                                       "value": "Agent status"
                                   },
                                   {
                                       "type": 0,
                                       "name": "desc_h_pos",
                                       "value": 0
                                   },
                                   {
                                       "type": 0,
                                       "name": "desc_v_pos",
                                       "value": 0
                                   },
                                   {
                                       "type": 0,
                                       "name": "desc_bold",
                                       "value": 1
                                   },
                                   {
                                       "type": 1,
                                       "name": "desc_color",
                                       "value": "F06291"
                                   },
                                   {
                                       "type": 0,
                                       "name": "value_h_pos",
                                       "value": 0
                                   },
                                   {
                                       "type": 0,
                                       "name": "value_size",
                                       "value": 25
                                   },
                                   {
                                       "type": 1,
                                       "name": "value_color",
                                       "value": "FFFF00"
                                   },
                                   {
                                       "type": 0,
                                       "name": "units_show",
                                       "value": 0
                                   },
                                   {
                                       "type": 0,
                                       "name": "time_h_pos",
                                       "value": 2
                                   },
                                   {
                                       "type": 0,
                                       "name": "time_v_pos",
                                       "value": 2
                                   },
                                   {
                                       "type": 0,
                                       "name": "time_size",
                                       "value": 10
                                   },
                                   {
                                       "type": 0,
                                       "name": "time_bold",
                                       "value": 1
                                   },
                                   {
                                       "type": 1,
                                       "name": "time_color",
                                       "value": "9FA8DA"
                                   },
                                   {
                                       "type": 1,
                                       "name": "thresholds.0.color",
                                       "value": "E1E1E1"
                                   },
                                   {
                                       "type": 1,
                                       "name": "thresholds.0.threshold",
                                       "value": "0"
                                   },
                                   {
                                       "type": 1,
                                       "name": "thresholds.1.color",
                                       "value": "D1C4E9"
                                   },
                                   {
                                       "type": 1,
                                       "name": "thresholds.1.threshold",
                                       "value": "1"
                                   }
                               ]
                           }
                       ]
                   }
               ],
               "userGroups": [
                   {
                       "usrgrpid": 7,
                       "permission": 2
                   }
               ],
               "users": [
                   {
                       "userid": 1,
                       "permission": 3
                   }
               ]
           },
           "id": 1
       }

Response:

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

See also