Evaluating values (Grafana, VIS, scripts)

How do I evaluate values across several years without adjusting everything every year?

In short: In VIS, Grafana and scripts, use the states under sourceanalytix.0.<device>.currentYear. Their IDs never change, not even at the turn of the year: SourceAnalytix resets them itself at the period change. For comparisons across several years, record the previous-period states with a history adapter, or read the yearly archive under sourceanalytix.0.<device>.<year>.

Which folder is for what

Folder	Content	Changes at the turn of the year?
currentYear.<category>.01_currentDay to 05_currentYear	current day, week, month, quarter, year	no, only the value starts over
currentYear.<category>.01_previousDay to 05_previousYear	completed previous period, e.g. yesterday or last year	no
currentYear.<category>.weeks, months, quarters	every week, month and quarter of the current year	no, all values are set to 0 on January 1
<year>.<category>.weeks, months, quarters	archive of a calendar year	yes, a new folder is added every year

<category> is consumed or delivered for consumption, costs or earnings for costs, and meterReadings for meter readings. What the previous-period states contain exactly is described under Where do I find yesterday, last week, last month (previous states)?.

How to evaluate across several years

1. Under "Instances", open the settings of the SourceAnalytix instance and go to the "Main settings" tab.
2. Under "Current year", check that "Previous period" is on, and for individual weeks, months or quarters of the current year, "Weeks", "Months" or "Quarters". On a new instance they are all on.
3. If you want to keep each year as its own folder, switch on "Weeks", "Months" or "Quarters" under "Year statistics". By default, only "Months" is on.
4. Save. The instance restarts and creates the states.
5. For long-term charts, record for example 03_previousMonth and 05_previousYear with a history adapter. Each value is written once per period, with the timestamp 23:59:59 on the last day of the period. This gives you a gapless series over the years without adjusting anything.

WARNING

If you switch off one of these options, SourceAnalytix deletes the matching states in the currentYear folder and in the folder of the current year. Folders of earlier years are kept.

You reach past years in the archive through the year in the path, for example sourceanalytix.0.<device>.2025.consumed.months.03_March. The yearly total is in <year>.consumedCumulative (costsCumulative for costs), and the meter reading in <year>.readingCumulative. How to insert the year dynamically in a script is described under How do I read SourceAnalytix values in a script?.

From v0.6.2: The weekly archive is in the folder of the year the calendar week belongs to. So week 53 of 2026 is under 2026 even if its last days fall in January 2027 (#1256). More on this under Why does week 52/53 show values in the new year?.

See also: Which datapoints do I use for Grafana/InfluxDB? · Which instance settings are there (periods, decimals)? · What happens at the turn of the year?

Which datapoints do I use for Grafana/InfluxDB?

In short: For daily, weekly and monthly bars, record the previous-period states, that is 01_previousDay, 02_previousWeek and 03_previousMonth under sourceanalytix.0.<device>.currentYear.<category>. They get exactly one value per period. For your own evaluations in Grafana, the total cumulativeReading is enough. All these states are numbers, so store them as numbers in InfluxDB too.

Which state for which chart

You want …	State under currentYear.<category>	What ends up in the database
Daily bars	01_previousDay	one value per day, with the timestamp 23:59:59 of that day
Compare weeks	02_previousWeek	one value per week, timestamp Sunday 23:59:59
Compare months	03_previousMonth	one value per month, timestamp last day 23:59:59
Course of the current day	01_currentDay	a value at every change, starting again from 0 at 0:00
Calculate everything yourself	cumulativeReading (directly under the technical ID)	the total, which never drops on its own when reset detection is on

SourceAnalytix rewrites the previous-period states at every period change, even if the value stays the same. A day with 0 kWh therefore appears as a bar of its own. The running values such as 01_currentDay, on the other hand, are only written when the value changes. They suit a live display, but not daily bars.

For costs, use the same states in the costs folder (earnings for feed-in). For the previous-period states to exist, the "Previous period" option must be on in the instance settings under "Main settings", "Current year".

How to set it up

1. In the admin, open the "Objects" tab and go to sourceanalytix.0.<device>.currentYear.consumed. From v0.7.0, the technical ID is in the source detail under "For experts".
2. For 01_previousDay (and if needed 02_previousWeek, 03_previousMonth), enable recording in your history adapter, for example InfluxDB.
3. Choose "number" as the data type if your history adapter asks for it.
4. In Grafana, plot the values as bars without any further summing. Each point is already the consumption of the whole period.

The first value only appears after the first period change, so for 01_previousDay after the next midnight.

TIP

If you want to show the current week or month next to the previous period, use 02_currentWeek and 02_previousWeek, or 03_currentMonth and 03_previousMonth, as the last value in a panel. The paths are fixed, so you never have to adjust the dashboard.

You set grouping, time range and colors in Grafana. That is not a SourceAnalytix feature.

See also: Evaluate across several years · Where do I find yesterday, last week, last month (previous states)? · Why are meter readings cumulative?

How do I visualize the values in VIS, Flot, HabPanel and the history?

In short: SourceAnalytix only provides states, no charts. For trends and bars, record the states you want with a history adapter (History, SQL or InfluxDB) and display them in Flot, eCharts, Grafana or a VIS widget. For tables and tiles without a database, use the state statisticsJson, which holds all values of the current year in one JSON.

Charts with the history

1. Choose the states you want to show. For daily bars that is sourceanalytix.0.<device>.currentYear.consumed.01_previousDay, for monthly bars 03_previousMonth. Which state suits what is explained under Which datapoints do I use for Grafana/InfluxDB?.
2. In the "Objects" tab, enable recording in your history adapter for these states.
3. In Flot or eCharts, create a chart with these states, as bars.
4. Embed the chart in VIS or HabPanel, for example as a Flot or eCharts widget.

Store and export daily values with their date

The previous-period states carry the timestamp 23:59:59 on the last day of the period they belong to, not the time of the rollover. The history adapter therefore stores yesterday's value under yesterday. This gives you a list of daily values with dates. You can export it with the tools of your history adapter.

If SourceAnalytix recovers a missed rollover later, for example after a restart, the value still gets the timestamp 23:59:59 on the day before the recovery.

Tables and tiles without a database

The state sourceanalytix.0.<device>.statisticsJson holds the running values, the previous periods, and the weekdays, weeks, months and quarters of the current year in one JSON. A VIS widget for JSON tables or a small script can build a table from it, without you binding every state individually. The structure is described under Is there a JSON with all values (for VIS)?.

Bind single values directly to the states under currentYear, for example 01_currentDay for "Today" and 01_previousDay for "Yesterday". If "Weekday" is on in the instance settings, the days of the current week are under currentYear.<category>.currentWeek, from 01_Monday to 06_Saturday and 07_Sunday.

See also: Evaluate across several years · Where do I find yesterday, last week, last month (previous states)? · Which week, month and quarter states and weekdays are there?

How do I read SourceAnalytix values in a script?

In short: Every value is an ordinary state under sourceanalytix.0.<device> that you read in a script with getState. The technical ID is the folder name of the source. From v0.7.0, you find it in the source detail under "For experts". For values of past years, read the yearly archive by inserting the year into the ID.

Finding the state ID

The ID is built like this: sourceanalytix.0.<device>.<folder>.<state>, for example sourceanalytix.0.strom.currentYear.consumed.03_currentMonth. The name or alias you give the source doesn't appear in the ID, only the technical ID.

• Sources from v0.7.0: The "Add a source" wizard builds the technical ID from the name you enter in the "Name" step. Under "For experts" you can choose it yourself there.
• Older sources: The technical ID is the ID of the source datapoint with __ instead of periods, such as modbus__0__inputRegisters__energy for modbus.0.inputRegisters.energy, unless you set your own output ID.

The command getUsedOutputIds returns all technical IDs of an instance together with their source datapoint. The answer is an object with the technical ID as the key and the ID of the source datapoint as the value. For a folder without a source, the value is null.

sendTo('sourceanalytix.0', 'getUsedOutputIds', {}, result => {
    log(JSON.stringify(result));
});

Reading this month and the same month last year

The months of the current year are under currentYear, and the months of completed years only in the folder of the respective year. There is no fixed "last year" folder. The month names are English and numbered, from 01_January to 12_December.

const root = 'sourceanalytix.0.strom';
const months = ['01_January', '02_February', '03_March', '04_April', '05_May', '06_June',
    '07_July', '08_August', '09_September', '10_October', '11_November', '12_December'];
const now = new Date();
const month = months[now.getMonth()];

const thisMonth = getState(`${root}.currentYear.consumed.03_currentMonth`).val;
const lastYearId = `${root}.${now.getFullYear() - 1}.consumed.months.${month}`;
const lastYear = existsState(lastYearId) ? getState(lastYearId).val : null;

log(`This month: ${thisMonth}, last year: ${lastYear}`);

IMPORTANT

The folder of the previous year only exists if the "Months" option was on under "Year statistics" in the instance settings during that year. It is on for a new instance. For weeks and quarters there are the options "Weeks" and "Quarters", which are off by default.

For last month or last year you don't need a date: they are in currentYear.consumed.03_previousMonth and currentYear.consumed.05_previousYear.

Reading the settings of a source

The settings are in the object of the source datapoint under common.custom, with the instance name as the key. Because the name contains a period, you need bracket notation: getObject('<source ID>').common.custom['sourceanalytix.0'].

NOTE

All SourceAnalytix states are read-only. Don't write to them from a script: SourceAnalytix overwrites them with the next value from the source or at the next period change. For corrections, use the actions in the instance settings, see Correct wrong values.

See also: Evaluate across several years · How do I name the datapoint (alias, output ID)? · Commands via sendTo