Cold Chain Excursion Cards

Who it’s for

An operator responsible for a cold chain — vaccines, food, or another temperature-limited shipment — who needs to answer “did this stay in range, and for how long did it not” without scrolling back through a raw telemetry chart. It reads whatever bounded value a monitored asset reports, so it fits a reefer, a cold room, or any other device with a compliance range, not only temperature.

What it does

An entity holding 5.2°C inside a 2-8°C range shows a green “OK” badge and a green value. An entity that spent 40 minutes above 8°C in the selected time window shows a red “EXCURSION” badge, the value in red, and “Out of range: 40m” with “Excursions: 1” underneath.

• Reads the whole series in the dashboard’s selected time window, not just the latest reading, so the excursion time and count are computed fresh every time — nothing is remembered between reloads, and nothing resets when the dashboard reopens
• Colors the current reading green or red against a minimum and maximum, so an out-of-range entity is visible at a glance
• Reports cumulative time out of range and the number of separate excursions within the current time window, with a minimum-duration filter so a brief blip — a door opening, a sensor hiccup — does not count as a real excursion
• Shows one card per bound entity, each labeled with its entity name once more than one is bound
• Takes the acceptable range from one of two sources, chosen with Range source: the same fixed minimum and maximum for every entity in the card, or a pair of keys each entity supplies for itself — useful when one card covers shipments with different compliance limits
• Shows a distinct message, per entity, when the expected key is not bound yet or the device has not reported
• Does not send commands, does not store or persist excursion history itself, and does not decide compliance on your behalf — the excursion time and count are only as complete as the time window you have selected, and a per-entity limit read from a key is its latest value, not a limit that can change partway through the window

How to set up

Data keys

Bind one entity per card. On each entity, bind a timeseries key named to match Value key name. Which other keys, if any, that entity needs depends on Range source:

Range source	Keys needed on each entity
Fixed values	Only the value key — the range comes from Minimum/Maximum acceptable value
From data keys (per entity)	The value key, plus a key named to match Minimum value key name and one named to match Maximum value key name

Key	Role	Type	Where to bind it	Description
Value key	The monitored reading	Timeseries	The regular data key list on the Data tab	Read across the whole selected time window, not just the latest point. This key’s own Units and Decimals fields (Data tab, per key) control what the card prints
Minimum value key	This entity’s own lower limit	Attribute / Timeseries	The Latest data keys field on the Data tab	Only used in “From data keys” mode. Only its latest value is used
Maximum value key	This entity’s own upper limit	Attribute / Timeseries	The Latest data keys field on the Data tab	Only used in “From data keys” mode. Only its latest value is used

Thresholds are usually static — a device profile default or a value set once per asset — so Minimum and Maximum value key bind as attributes through the separate Latest data keys field, not the main data key list. That field also accepts timeseries keys; either way only the latest value is read.

Data

Setting	Default	Effect
Value key name	temperature	The data key name read as the monitored value for each entity

Range

Setting	Default	Effect
Range source	Fixed values	Switches every entity in the card between a shared fixed range and a range each entity supplies through its own keys
Minimum acceptable value	2	The lower bound of the compliant range, in Fixed values mode
Maximum acceptable value	8	The upper bound of the compliant range, in Fixed values mode
Minimum value key name	minLimit	The key name read as an entity’s lower limit, in From data keys mode
Maximum value key name	maxLimit	The key name read as an entity’s upper limit, in From data keys mode
Ignore excursions shorter than (minutes)	5	Excursions shorter than this are not counted, to filter out brief blips

Set the widget’s time window (the standard control above the card, same as any timeseries widget) to the compliance period you want to review — for example the last 24 hours or the last 7 days. The excursion time and count always describe that window, not an all-time total.

How to customize

• To change the color of an in-range entity — edit In-range color
• To change the color of an entity in excursion — edit Excursion color
• To change the unit printed after the value — set Units on the Value key itself, on the Data tab
• To show more or fewer decimal places — set Decimals on the Value key itself, on the Data tab
• To change the size or font of the value — edit Value font

Tips

• A door opening usually looks like a short excursion. Raise Ignore excursions shorter than past your normal door-open time so routine access does not inflate the excursion count.
• Mixing shipments with different limits in one card. Switch Range source to “From data keys” and bind each entity’s own minimum and maximum as attributes — a device profile default, or a value set once per asset, both work.