Table of Contents
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._timeperiodAlternatively, 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._timeperiodAlternatively, 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.
{
"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: