Value card schema

Use value cards to show the value of data items.

The structure of the value card schema is as follows:

For the dashboard schema, see the Dashboard JSON reference topic.

For more information about how to use a value card, see the Value card topic.

Cards

A value card is defined in a cards array.

Example: 

{
    "cards": [{
        "id": "fuel_flow",
        "size": "LARGE",
        "title": "Fuel flow",
        "type": "VALUE",
        "content": {
            "attributes": [{
                    "dataSourceId": "fuel_flow_rate",
                    "dataFilter": {
                        "deviceid": "73000"
                    },
                    "label": "Latest - 73000",
                    "precision": 3,
                    "thresholds": [{
                        "color": "#F00",
                        "comparison": ">",
                        "icon": "Warning",
                        "value": 2
                    }]
                },
                {
                    "dataSourceId": "fuel_flow_rate2",
                    "dataFilter": {
                        "deviceid": "73001"
                    },
                    "label": "Latest - 73001",
                    "precision": 3,
                    "thresholds": [{
                        "color": "#F00",
                        "comparison": ">",
                        "icon": "Warning",
                        "value": 2
                    }]
                },
                {
                    "dataSourceId": "fuel_flow_rate_min",
                    "dataFilter": {
                        "deviceid": "73000"
                    },                    
                    "label": "Minimum",
                    "precision": 3,
                    "thresholds": [{
                        "color": "#5aa700",
                        "comparison": ">",
                        "icon": "Checkmark outline",
                        "value": -2
                    }]
                },
                {
                    "dataSourceId": "fuel_flow_rate_max",
                    "dataFilter": {
                        "deviceid": "73000"
                    },                    
                    "label": "Maximum",
                    "precision": 3,
                    "thresholds": [{
                        "color": "#5aa700",
                        "comparison": "<",
                        "icon": "Checkmark outline",
                        "value": 5
                    }]
                }
            ]
        },
        "dataSource": {
            "range": {
                "type": "periodToDate",
                "count": -24,
                "interval": "hour"
            },
            "attributes": [{
                    "aggregator": "last",
                    "attribute": "fuel_flow_rate",
                    "id": "fuel_flow_rate"
                },
                {
                    "aggregator": "last",
                    "attribute": "fuel_flow_rate",
                    "id": "fuel_flow_rate2"
                },
                {
                    "aggregator": "min",
                    "attribute": "fuel_flow_rate",
                    "id": "fuel_flow_rate_min"
                },
                {
                    "aggregator": "max",
                    "attribute": "fuel_flow_rate",
                    "id": "fuel_flow_rate_max"
                }
            ],
            "groupBy": ["deviceid"]
        }
    }],
    "title": "Example"
}

Table 1. Cards

Parameter Description Type Required
id The id identifies the card in the JSON file. The ID must be unique per dashboard. string yes
size The size of the card. Valid values are SMALL, SMALLWIDE, MEDIUM, MEDIUMTHIN, MEDIUMWIDE, LARGE, LARGETHIN, and LARGEWIDE. If four or more values are displayed, size must be set to at least LARGE. string yes
title The title to display on the card. string yes
type The type of card. Use VALUE. string yes
content A definition of the content to display on the card. object yes
dataSource Information about the source of each data item that is displayed on the card or used in thresholding. object yes
fontSize In the beta environment, you can set the font size for the text. number no
isNumberValueCompact In the beta environment, you can abbreviate numbers by using K, M, or B. For example, show 1.2K instead of 1,200. boolean no
timeRange The relative time range to select by default for the card. Valid values are last24Hours, last7Days, lastMonth, lastQuarter, lastYear, thisWeek, thisMonth, thisQuater and thisYear. string no

Content

In cards.content, specify the information to display on a value card, such as values and alerts.

Example:

{
    "content": {
        "attributes": [{
                "dataSourceId": "fuel_flow_rate",
                "label": "Latest",
                "precision": 3,
                "thresholds": [{
                    "color": "#F00",
                    "comparison": ">",
                    "icon": "Warning",
                    "value": 2
                }]
            },
            {
                "dataSourceId": "fuel_flow_rate_min",
                "label": "Minimum",
                "precision": 3,
                "thresholds": [{
                    "color": "#5aa700",
                    "comparison": ">",
                    "icon": "Checkmark outline",
                    "value": -2
                }]
            },
            {
                "dataSourceId": "fuel_flow_rate_max",
                "label": "Maximum",
                "precision": 3,
                "thresholds": [{
                    "color": "#5aa700",
                    "comparison": "<",
                    "icon": "Checkmark outline",
                    "value": 5
                }]
            }
        ]
    }
}

Table 2. Content

Parameter Description Type Required
attributes Defines the data items that are displayed as values on the card. array yes
groupBy If you define a dataFilter for any of the values, group the results by group the dimensions, the device IDs, or the alert fields that you specify. For example, "groupBy": ["deviceid", "manufacturer"] or "groupBy": ["severity"] array no

Attributes

In cards.content.attributes, specify the data items that are displayed as values on the card.

Example:

{
    "attributes": [{
            "dataSourceId": "fuel_flow_rate",
            "label": "Latest",
            "precision": 3,
            "thresholds": [{
                "color": "#F00",
                "comparison": ">",
                "icon": "Warning",
                "value": 2
            }]
        },
        {
            "dataSourceId": "fuel_flow_rate_min",
            "label": "Minimum",
            "precision": 3,
            "thresholds": [{
                "color": "#5aa700",
                "comparison": ">",
                "icon": "Checkmark outline",
                "value": -2
            }]
        },
        {
            "dataSourceId": "fuel_flow_rate_max",
            "label": "Maximum",
            "precision": 3,
            "thresholds": [{
                "color": "#5aa700",
                "comparison": "<",
                "icon": "Checkmark outline",
                "value": 5
            }]
        }
    ]
}

Table 3. Content attributes

Parameter Description Type Required
dataSourceId A unique ID for the data item whose value is displayed. The data item must also be defined in the dataSource object. If you set "type": "alert" in the cards.dataSource object, then set "dataSourceId": "count". string yes
dataFilter A definition of a filter to apply to the attribute. For example, you might filter the maximum fuel flow rate to show the maximum value for a specific device, a specific plant, or model. The filter can be a dimension value or a device ID. You might filter by an alert field value, such as critical alerts. If you specify a data filter, you must include the filter in the groupBy field in the dataSource configuration. Yoou must specific a dataFilter on a summary dashboard. object
label The label to assign to the value. string no
precision If the data item has a numeric value, the level of precision to display. integer no
unit Specify the unit that the data item is measured in, for example, %. string no
thresholds A definition of an alert on the data item. array no
DataFilter

In cards.content.attributes.dataFilter, you can specify a filter to apply to the attribute or value.

Example: - Filter by device ID

{
    "dataFilter": {
        "deviceid": "73000"
    }
}

Example: - Filter by dimension

{
    "dataFilter": {
        "manufacturer: "Rentech"
    }
}

Example: - Filter by an alert field

{
    "dataFilter": {
        "severity: "Critical"
    }
}

Specify a deviceid, a dimension name and value, or an alert field and value. You can only specify one filter for each attribute. If you specify a data filter, you must specify the filter in the groupBy field in the cards.dataSource configuration.

Thresholds

In cards.content.attributes.thresholds, define alerts at the dashboard level. You can define alerts on the values that are displayed on the card.

Example:

{
    "thresholds": [{
        "color": "#5aa700",
        "comparison": ">",
        "icon": "Checkmark  outline",
        "value": -2
    }]
}

Table 4. Thresholds

Parameter Description Type Required
color The color of the alert. Specify the color using its hex code or its name. The hex code must start with # and be 7 characters long. If you specify the name of the color, the name must be in lower case, for example, purple. string no
comparision The comparison operator to apply to the threshold value. Valid values are >, <, or =. string no
icon The icon to display if an alert is generated. Specify an icon from the UI icons library in the Carbon Design System. Use the icon name from the design system. For example, to assign an Warning filled icon, enter "icon": "Warning filled". For more information about specifying an icon, see the Icons section of Dashboard features. string no
value The threshold value. string no

DataSource

In cards.dataSource, connect the information that is displayed on the value card or that is used in alerts to data items in the data lake.

Example: 

{
    "dataSource": {
        "range": {
                "type": "periodToDate",
                "count": -24,
                "interval": "hour"
            },
        "attributes": [{
            "aggregator": "last",
            "attribute": "fuel_flow_rate",
            "id": "fuel_flow_rate"
        }]
    }
}

Table 5. Data source

Parameter Description Type Required
range Specifies a time range for the data items. object no
type Set "type": "alert" to show alert information in the value card. string no
groupBy If you added a dataFilter in cards.content.attributes.dataFilter, add the filter type to groupBy. object no
attributes A definition of the source of the data that is used in values and in thresholds. If you set "type": "alert", omit the attributes array.
Note: All data item types, that is alerts, metrics and dimensions, are supported.		 array yes

Range

In cards.dataSource.range, specify a time range to apply to the whole time series.

Example:

{
    "range": {
        "type": "periodToDate",
        "count": -7,
        "interval": "day"
    }
}

Table 6. range

Parameter Description Type Required
type Valid values are rolling or periodToDate. Rolling period rolls to the current date whereas periodToDate ends on the first day of each calendar month. If you select periodToDate, and you set to the range to the last 2 months, on Dec 2, the date range is up until the 1st of December (the first day of the current calendar month). string no
count A negative number representing the number of interval units to subtract from the dashboard end date. For example, if the dashboard end date is today and the time interval is day, enter -1 to display the last 24 hours of data in the card. string yes
interval Time interval. Valid values are hour, day, week, month, quarter, year. string yes

Attributes

In cards.dataSource.attributes, specify the aggregation method to apply to each data item.

Example: 

{
    "attributes": [{
        "aggregator": "last",
        "attribute": "fuel_flow_rate",
        "id": "fuel_flow_rate"
    }]
}

Table 7. Data source attributes

Parameter Description Type Required
aggregator An aggregation method to apply to the data item at the dashboard level. Valid values min, max, mean, first, count, std, sum, last. If you do not specify an aggregator for a metric, a value of last is used. Do not specify an aggregator for a dimension. string no
attribute The data item name. Corresponds to a name in the data lake. string yes
id An ID for the data item. The ID corresponds to the dataSourceId. string yes