12 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 Item ID.

Parameter behavior:
- required
Show 0 show 1 - Description;
2 - Value;
3 - Time;
4 - Change indicator.

Default: 1, 2, 3, 4 (all enabled).

Note: To configure multiple values, create a dashboard widget field object for each value.
Enable host selection 0 dynamic 0 - (default) Disabled;
1 - Enabled.
Advanced configuration 0 adv_conf 0 - (default) Disabled;
1 - Enabled.

Advanced configuration

The following parameters are supported if Advanced configuration is set to "Enabled".

The number in the Thresholds property name (e.g. thresholds.color.0) 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. "threshold.threshold.0":"5""threshold.threshold.0":"1"; "threshold.threshold.1":"1""threshold.threshold.1": "5").

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

Default: "" (empty).
Thresholds
Color 1 thresholds.color.0 Hexadecimal color code (e.g. FF0000).
Threshold 1 thresholds.threshold.0 Any string value.
Description

The following parameters are supported if Advanced configuration is set to "Enabled", and 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 Valid 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 parameters are supported if Advanced configuration is set to "Enabled", and Show is set to "Value".

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

Default: 2.
Size 0 decimal_size Valid 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 Valid 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 Valid 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 parameters are supported if Advanced configuration is set to "Enabled", and 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 Valid 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 parameters are supported if Advanced configuration is set to "Enabled", and 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).

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": 4,
                               "height": 3,
                               "view_mode": 0,
                               "fields": [
                                   {
                                       "type": 4,
                                       "name": "itemid",
                                       "value": 42266
                                   },
                                   {
                                       "type": 0,
                                       "name": "show",
                                       "value": 1
                                   },
                                   {
                                       "type": 0,
                                       "name": "show",
                                       "value": 2
                                   },
                                   {
                                       "type": 0,
                                       "name": "show",
                                       "value": 3
                                   },
                                   {
                                       "type": 0,
                                       "name": "adv_conf",
                                       "value": 1
                                   },
                                   {
                                       "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.color.0",
                                       "value": "E1E1E1"
                                   },
                                   {
                                       "type": 1,
                                       "name": "thresholds.threshold.0",
                                       "value": "0"
                                   },
                                   {
                                       "type": 1,
                                       "name": "thresholds.color.1",
                                       "value": "D1C4E9"
                                   },
                                   {
                                       "type": 1,
                                       "name": "thresholds.threshold.1",
                                       "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