Consumption and Snapshots

About 9 min read

A snapshot is a single value calculated for a calendar period from the archive (log) records of a tag: today's energy consumption, yesterday's average power, last month's highest temperature and so on. Snapshots are fetched from the server in a single batch request when the page opens and are bound to the widgets on the page like an ordinary tag. No extra code or special widget is needed.

There are two kinds of snapshots:

Kind	Prefix	What it calculates	Suitable data
History	__hist	The sum, average, minimum, maximum or last value of the archive records in the period	Instant measurements: power (kW), voltage (V), current (A), temperature
Consumption	__cons	The increase of the counter value within the period (counter difference)	Continuously increasing counters: active/reactive energy (kWh), water, gas

Use __cons for a continuously increasing value such as an energy meter, and __hist for an instant measurement.

Archive records are required

A snapshot is calculated from the archive records of the tag. If the tag has no log definition, the server cannot find the snapshot source and no value arrives. If the tag has more than one log definition, the log definition created first is used.

Structure of a Snapshot Name

A snapshot name consists of four parts separated by dots:

<kind>.<period>.<aggregation>.<tag>

Part	Values	Example
Kind	__hist or __cons	__cons
Period	The periods table below	thismonth
Aggregation	sum, avg, min, max, last	sum
Tag	Tag name (relative to the tag prefix of the page; see Tag name and page prefix)	EA

Examples:

__cons.today.sum.EA                today's energy consumption
__cons.yesterday.sum.EA            yesterday's energy consumption
__cons.month[-1].sum.EA            last month's energy consumption
__hist.today.avg.AktifGuc          today's average active power
__hist.thismonth.max.Sicaklik      this month's highest temperature

• Names are not case-sensitive; Month[-1] and month[-1] are the same.
• If the aggregation part is omitted, sum is used.
• The __const spelling seen on older pages is accepted as __cons; use __cons on new pages.

Periods

Period	Meaning	How often the value is refreshed
today	Today	About 45 seconds
yesterday	Yesterday	1 hour
thisweek	This week	10 minutes
lastweek	Last week	1 hour
thismonth	This month	10 minutes
lastmonth	Last month	1 hour
thisyear	This year	30 minutes
lastyear	Last year	1 hour

For older periods, use the offset notation: day[N], week[N], month[N] and year[N]. N is 0 or a negative integer:

• day[0] is today, day[-2] is two days ago.
• month[-1] is last month, month[-3] is the month three months ago.
• When N is 0 the value is refreshed like a current period; when it is negative, like a completed period.

Periods are aligned to the calendar in the time zone of the browser that opened the page; for example, today starts at local midnight.

Aggregation

Value	Meaning
sum	Sum
avg	Average
min	Minimum
max	Maximum
last	Last value

For consumption (__cons) snapshots, use sum for the total consumption of the period.

Snapshot Name Builder

Instead of typing the snapshot name by hand, you can use the Snapshot name builder in the bindings panel of the Page Editor:

1. Select the widget and open the bindings tab in the right panel (see Page Editor).
2. Click the Snapshot name builder button.
3. Use the button next to the Tag field to select a tag that has history records. A real tag (Channel.Device.Tag) must be selected; system tags, expressions and snapshot names cannot be used.
4. Select History (__hist) or Consumption (__cons) as the Kind.
5. Select the Period. When Day (with offset), Week (with offset), Month (with offset) or Year (with offset) is selected, the Offset (0 = current, -1 = previous) field appears.
6. Select the Aggregation method. The default is Average for history and Sum for consumption.
7. Check the name in the Preview field and click the Insert button.

The builder produces the absolute form that contains the full name of the selected tag (for example, MTCP01.Sayac01.__cons.today.sum.EA). This form works independently of the tag prefix of the page.

Binding to a Widget

The snapshot name is written in the value binding of the widget instead of a tag name. For widgets such as a value label, gauge or text, bind the value property (processValue). When the page is opened in preview or in the viewer, the value is filled in automatically.

• The value stays empty until the first query completes, then it is refreshed at the interval above for its period.
• If the same snapshot is used in more than one widget, the server is queried once.
• Snapshots can also be used in expressions. The snapshot name is written in quotes:

'__cons.month[-1].sum.EA' + '__cons.thismonth.sum.EA'
'MTCP01.Trafo1.__cons.today.sum.EA' + 'MTCP01.Trafo2.__cons.today.sum.EA'

Tag Name and Page Prefix

If a Tag Prefix is defined for the page (for example, when the same page is opened for different devices), the tag in the snapshot name is resolved relative to this prefix. A snapshot name can be written in four forms:

Notation	Tag Prefix	Tag read	When
__cons.thismonth.sum.EA	MTCP01.Trafo1.	MTCP01.Trafo1.EA	If the prefix ends with a dot
.__cons.thismonth.sum.EA	MTCP01.Trafo1	MTCP01.Trafo1.EA	If the prefix ends without a dot; the leading dot is added as a separator
__cons.thismonth.sum._EA	MTCP01.Trafo1.T	MTCP01.Trafo1.T_EA	If the tag name continues the prefix; no dot is added in between
MTCP02.Trafo2.__cons.month[-1].sum.EA	Any	MTCP02.Trafo2.EA	For a specific tag (absolute form); no prefix is added

If the page has no tag prefix, the tag name in the first form is used as it is.

The Enerji Analizörü (Energy Analyzer) template page of the sample project uses the second form: when the page is opened with the prefix Internal.Trafo1_EA, the binding .__cons.today.sum.KWH reads the consumption from the log of the tag Internal.Trafo1_EA.KWH (see Explore the sample project).

Do not use @NOP::

Do not put @NOP:: in front of snapshot names. On pages with a tag prefix, the value then never arrives; the bindings panel also shows a warning. For a snapshot independent of the prefix, use the absolute form (Channel.Device.__cons...).

Missing Data and Partial Period Indicators

Consumption values also report whether the data of the period is complete. Two states are calculated for each period:

State	Icon	When
Data gap	Warning icon	Archive records are missing in the period; consumption may appear lower than it is.
Partial period	Clock icon	The period has not ended yet (today, this month) or the selected time range covers only part of the period.

Hovering over the icon shows an explanation: Data gap in this period; consumption may be understated, Period not finished yet; value is partial and, when the records do not cover the whole period, Data coverage: …%.

How a Data Gap Is Determined

A data gap can be determined only for log definitions whose Log Type is Cyclic, that is, logs that record at fixed Interval periods. For such a log, a period is marked as a data gap when:

• there are no records in the period,
• there are no records at the start or end of the period for longer than three times the log interval (at least 5 minutes),
• the number of records in the period is less than 90% of the number expected from the log interval.

For log types that record when the value changes or on a trigger (On Change, On Trigger Change, Cyclic While Triggered and so on), it is normal for no records to be created while the value stays constant; for these logs, no data gap is marked based on the record count.

Regardless of the log type, for logs whose Consumption Value Type is Cumulative, a period with no base reading before it is also marked as a data gap: the first period of a new counter, or a period of a counter that has not written records for more than 31 days. For the calculation rule, see the Consumptions page; snapshots, widgets, and the Consumptions and Consumption Pivot screens use the same rule.

In KPI Widgets: Data Coverage Indicator

These widgets bound to a __cons snapshot can show an icon next to the value: Value label, Gauge, Linear gauge, Circular progress, Text and Paragraph.

When the icons are shown is selected with the Data Coverage Indicator (coverageIndicator) setting of the widget:

Option	Value	Behavior
Only data gaps	gap	Default. A warning icon is shown if the period has a data gap.
Gaps and partial periods	all	In addition to data gaps, a clock icon is also shown for periods that have not ended yet.
Off	none	No icon is shown.

• The setting works only with __cons snapshot bindings; no icon is shown for __hist snapshots or ordinary tags.
• The icons are not visible in the editor; they are shown when the page is opened in preview or in the viewer.

In Charts and Tables

The Chart, Pie chart, Data table and the History > Consumption Pivot screen use the indicators automatically when they show consumption data; there is no separate setting for them:

• If one of the periods shown has a data gap, the message Some periods have data gaps; consumption may be understated. appears with a warning icon.
• If the last period is not complete yet, the message The latest period is not finished yet; its values are partial. appears with a clock icon.
• In the chart, the points of periods with a data gap are drawn with an orange border, and the points of incomplete periods are drawn semi-transparent.

Consumption Reports

Besides page widgets, consumption values can also be examined on these screens:

• History > Consumptions: Shows the consumption of the selected tags by time range as a chart and a table.
• History > Consumption Pivot: Shows consumption by period and tag as a pivot table; data gap and partial period information is shown here too.

For the common use of the report screens, see the Reporting page.

Common Mistakes

Symptom	Cause and solution
No value arrives	The tag has no log definition, or the tag name does not combine correctly with the tag prefix of the page. Produce the absolute form with the snapshot name builder.
No value arrives on a page with a tag prefix	The snapshot name starts with @NOP::. Remove @NOP:: or use the absolute form.
The energy value is far too large	__hist was used for a counter, so the counter values themselves are summed. Use __cons for counters.
An offset period is not accepted	N was written as a positive number. Only 0 or negative values are valid (month[-1]).
The value updates late	Values are refreshed according to their period; for example, thismonth about every 10 minutes. This behavior cannot be changed.