Image card schema

Use image cards to display images and to associate data items with hotspot areas on the image.

The structure of the image card schema is as follows:

Cards
- Content
  - Hotspots
- DatatSource
  - Attributes
  - Range

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

Cards

An image card is defined in a cards array.

Example:

{
    "cards": [{
        "id": "sensor-readings-image",
        "size": "LARGE",
        "title": "Sensor Readings",
        "type": "IMAGE",
        "content": {
            "alt": "Sensor Readings",
            "zoomMax": 5,
            "id": "world_map",
            "hotspots": [{
                "icon": "carbon-icon",
                "color": "'#0F0",
                "content": {
                    "title": "Sensor readings",
                    "description": "Image card for Sensor readings",
                    "attributes": [{
                        "dataSourceId": "temp_last",
                        "label": "Temperature",
                        "unit": "F"
                    }]
                },
                "type": "fixed",
                "locations": [{
                    "x": "22.85",
                    "y": "33.183"
                }],
                "thresholds": [{
                    "dataSourceId": "temp_last",
                    "comparison": ">=",
                    "value": 100,
                    "color": "red",
                    "icon": "Close filled"
                }]
            }]
        },
        "dataSource": {
            "attributes": [{
                    "aggregator": "last",
                    "attribute": "temp",
                    "id": "temp_last"
                },
                {
                    "aggregator": "last",
                    "attribute": "humidity",
                    "id": "humidity_last"
                },
                {
                    "aggregator": "last",
                    "attribute": "wind",
                    "id": "wind_last"
                },
                {
                    "aggregator": "last",
                    "attribute": "conditions",
                    "id": "conditions_last"
                }
            ],
            "range": {
                "type": "rolling",
                "count": -1,
                "interval": "day"
            }
        }
    }],
    "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 `MEDIUM`,`MEDIUMWIDE`, `LARGE`, and `LARGEWIDE`. Migrate your card size accordingly.	string	yes
`title`	The title to display on the card.	string	yes
`type`	The type of card. Use `IMAGE`.	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 that is used in thresholding.	object	yes
`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 image to display. If you include hotspots, specify the information to display in the hotspot.

Example:

{
    "content": {
        "alt": "Sensor Readings",
        "zoomMax": 5,
        "id": "world_map",
        "hotspots": [{
            "icon": "carbon-icon",
            "color": "'#0F0",
            "content": {
                "title": "Sensor readings",
                "description": "Image card for Sensor readings",
                "attributes": [{
                    "dataSourceId": "temp_last",
                    "label": "Temperature",
                    "unit": "F"
                }]
            },
            "type": "fixed",
            "locations": [{
                "x": "22.85",
                "y": "33.183"
            }],
            "thresholds": [{
                "dataSourceId": "temp_last",
                "comparison": ">=",
                "value": 100,
                "color": "red",
                "icon": "Close filled"
            }]
        }]
    }
}

Table 2. Content

Parameter	Description	Type	Required
`hideMinimap`	Hide the minimap on the image. The minimap helps to orient you when you zoom in on the image. The default value is `true`.	BOOLEAN	no
`hideHotspots`	Hide hotspots on the image. The default value is `tfalse`.	BOOLEAN	no
`hideZoomControls`	Hide the zoom controls on the image. The default value is `true`.	BOOLEAN	no
`zoomMax`	The maximum zoom level on the image. With `zoomMax`, you can zoom in beyond the 1:1 resolution of an image. Set `zoomMax` if you want to differentiate hotspots that are close together.	integer	no
`alt`	Alternative text for the image.	string	no
`id`	The ID of the image. The ID must match an ID in the database. Note: When you add an image, you can associate multiple entities with a single image ID. You can associate different image files with each device. In a device dashboard, the image that is associated with that instance is displayed. If no image is found for the instance, the device image is displayed, if available.	string	yes
`hotspot`	A collection of hotspot objects. Each hotspot object in the array provides a definition of the hotspot. The hotspot definition might apply to a single location on the image or multiple locations. If you want to include a simple image on a card, omit the hotspot configuration.	array	no

Hotspots

In cards.content.hotspots, define the appearance of the hotspot, the content to display and the icon to use.

Example:

{
    "hotspots": [{
        "icon": "Information filled",
        "color": "'#0F0",
       "content": {
            "title": "Sensor readings",
            "description": "Image card for Sensor readings",
            "attributes": [{
                "dataSourceId": "temp_last",
                "label": "Temperature",
                "unit": "F"
                }]
            },
        "type": "fixed",
        "locations": [{
            "x": "22.85",
            "y": "33.183"
        }],
        "thresholds": [{
            "dataSourceId": "temp_last",
            "comparison": ">=",
            "value": 100,
            "color": "red",
            "icon": "Close filled"
        }]
    }]
}

Table 3. Hotspots

Parameter	Description	Type	Required
`icon`	The name of the hotspot icon. 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 Information filled icon, enter `"icon": "Information filled"`. If no icon is specified, the hotspot is rendered as a semi-transparent circle. For more information about specifying an icon, see the Icons section of Dashboard features.	string	no
`color`	Defines the color of the hotspot icon. 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
`content`	Define the information to display in each hotspot.	object	yes
`locations`	Define the location of the hotspot on the image card.	array	yes
`thresholds`	Define alerts to apply to the hotspot.	array	no
`borderWidth`	Define the width of the hotspot border.	string	no
`backgroundOpacity`	Level of opacity in the bakground. Use a value between 0 and 100.	string	no
`fontSize`	Font size for the hotspot text.	string	no
`type`	Defines the type of hotspot. Set to `fixed` to define the location of the hotspot by using `x` and `y` coordinates. Set to `dynamic`, to specify the location using data items. Set to `text` to display the hotspot as a label that this always visible.	string	yes
`fontSize`	Font size for the hotspot text.	string	no
`fontSize`	Font size for the hotspot text.	string	no
`fontColor`	If setting a label, use to set the font color.	string	no
`backgroundColor`	If setting a label, use to set the background color of the label.	string	no
`borderColor`	If setting a label, use to set the border color of the label.	string	no

Content

In cards.content.hotspots.content, specify a title to display on each hotspot and specify the data items to display in each hotspot location.

Example:

{
    "content": {
        "title": "Sensor readings for {deviceid} ",
        "description": "Image card for Sensor readings",
        "attributes": [{
            "dataSourceId": "temp_last",
            "label": "Temperature",
            "unit": "F"
        }]
    }
}

Table 4. Hotspots content

Parameter	Description	Type	Required
`title`	The title to display on the hotspot. You can add {deviceid} to the title to display the ID of the associated device.	string	yes
`description`	A description of the hotspot content.	string	no
`attributes`	Defines the data items to display in each hotspot.	object	yes

Attributes

In cards.content.hotspots.content.attributes, specify the data items to display in each hotspot. The same data items are displayed in each hotspot on a card.

Example:

{
    "attributes": [{
        "dataSourceId": "temp_last",
        "label": "Temperature",
        "unit": "F"
    }]
}

Table 5. 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.	string	yes
`Label`	The label to use for the data item.	string	yes
`unit`	Specify the unit that the data item is measured in, for example, `%`.	string	no

Locations

In cards.content.hotspots.locations, specify each hotspot location using a location object.

Examples:

The following is an example of specifying the location by using x and y coordinates. You must use this approach for labels.

{
    "locations": [{
        "x": 65,
        "y": 65.5
    }]
}

In the following example, the x and y coordinates are specified using data items.

{
    "locations": [{
        "xDataSourceId": "x",
        "yDataSourceId": "y"
    }]
}

Table 6. Locations

Parameter	Description	Type	Required
`x`	Percentage placement from the left of the image card. The valid range is 0 to 100%. For 10%, enter a value of 10. For help with defining the `x` value, see Defining the location of hotspots	string	no
`y`	Percentage placement from the top of the image card. The valid range is 0 to 100%. For 10%, enter a value of 10. For help with defining the `y` value, see Defining the location of hotspots	string	no
`xDataSourceId`	Represents the percentage placement from the left of the image card. Enter `x`. Specify the actual value in a data item named `x` in the data lake.	string	no
`yDataSourceId`	Represents the percentage placement from the top of the image card. Enter `y`. Specify the actual value in a data item named `y` in the data lake.	string	no

Thresholds

In cards.content.hotspots.thresholds, define alerts.

Example:

{
    "thresholds": [{
        "dataSourceId": "temp_last",
        "comparison": ">=",
        "value": 100,
        "color": "red",
        "icon": "Close filled"
    }]
}

Table 8. 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

DatatSource

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

Example:

{
    "dataSource": {
        "attributes": [{
                "aggregator": "last",
                "attribute": "temp",
                "id": "temp_last"
            },
            {
                "aggregator": "last",
                "attribute": "humidity",
                "id": "humidity_last"
            },
            {
                "aggregator": "last",
                "attribute": "wind",
                "id": "wind_last"
            },
            {
                "aggregator": "last",
                "attribute": "conditions",
                "id": "conditions_last"
            }
        ],
        "range": {
            "type": "rolling",
            "count": -1,
            "interval": "day"
        }
    }
}

Table 9. dataSource

Parameter	Description	Type	Required
`attributes`	A definition of the source of the data that is used in hotspot and in alerts.	array	yes
`range`	Specifies a time range for the data items.	array	no

Attributes

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

Example:

{
    "attributes": [{
            "aggregator": "last",
            "attribute": "temp",
            "id": "temp_last"
        },
        {
            "aggregator": "last",
            "attribute": "humidity",
            "id": "humidity_last"
        },
        {
            "aggregator": "last",
            "attribute": "wind",
            "id": "wind_last"
        },
        {
            "aggregator": "last",
            "attribute": "conditions",
            "id": "conditions_last"
        },
        {
            "attribute": "y",
            "id": "x"
        },
        {
            "attribute": "y",
            "id": "y"
        }
    ]
}

Table 10. dataSource 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 aggreator, a value of `last` is used.	string	yes
`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

Range

In cards.dataSource.range, you specify the time range for all data items that are displayed on the card or are used in threshold definitions.

Example:

{
    "range": {
        "type": "rolling",
        "count": -1,
        "interval": "day"
    }
}

Table 11. 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	yes
`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