Report API

The report.preset procedures create, read, update, and delete reports, which the API calls presets. Every setting of each view, with its editor label and default, is listed in the chart, table, time bars, histogram, calendar, hourly matrix, state duration, and Sankey references. Create a chart report shows a complete request.

A new preset needs a title. Timezone, range, CSV, snapshot sharing, and comment settings are optional and take the defaults of a new report in Setup. The created preset opens at /workspace/$workspaceId/reports/$presetId, using the returned ID.

Titles, descriptions, label, and units accept a plain string or a localized object such as { "en": "Temperature", "pl": "Temperatura" }. freezeFromLive returns them as stored on the parameter.

Preset fields

Field	Editor label	Default on create
title	Title	Required
description	Description	null
parameters	Parameters	[]
representations	Views	{}
layout	Layout	{ "type": "simple", "rows": [] }
defaultTimeRange	Default time range	{ "type": "last-days", "days": 7 }
immutableTimeRange	Lock time range	false
timezone	Timezone	"browser"
allowAddComments	Add comments	true
displayCommentsSummary	Comments summary	true
allowSigning	Sign report	false
allowRender	Show snapshot sharing button	false
showEditButton	Show edit report button	true
exportToCsv	Show CSV export button	null (no CSV export)

exportToCsv is { parameterIds, cadence, numericAggregation, integerAggregation, stringAggregation }; the editor starts it with cadence: "1h", numericAggregation: "average", and latest for integers and strings. See On the report.

create and update require Editor access. update replaces each field it receives. Responses also carry revision. With that value as baseRevision, update, delete, and saveTemporary fail with setup_conflict when the preset changed in the meantime.

List

{ "workspaceId": "$workspaceId" }

Returns reportPresets: id, title, description, revision, updatedAt. get returns the full recipe. Unsaved temporary presets are omitted; get by ID still returns them. Temporary presets are never included in hmi pull, local workspaces, or archives.

Get

{ "id": "$presetId" }

Where-used

report.preset.listByParameterIds lists the presets that include any of the given parameter IDs, for example to warn before parameter.deleteSelection. It takes parameter IDs, not branch IDs, up to 1000. Unsaved temporary presets are omitted. Deleting a parameter is never refused because a preset includes it: the preset loses that parameter, and views skip it.

{ "workspaceId": "$workspaceId", "parameterIds": ["$parameterId"] }

Delete

Deleting a preset is permanent and also deletes its comments. Shared snapshots of the preset are kept.

{ "id": "$presetId" }

Freeze from live

report.preset.freezeFromLive reads live parameters and returns them as parameter snapshots for a report; it does not save anything. The returned parameters fit the parameters field of create and update. Up to 100 unique IDs; duplicates are dropped, and more unique IDs fail with report_preset_freeze_limit_exceeded. IDs that cannot be frozen are returned in skipped with the reason missing or unsupported_value_type. New parameter colors follow a 16-color high-contrast sequence (blue, then orange, green, red, …). Any workspace member can call it.

create and update accept any label, for example "Channel 1 · Sensor temperature" to tell apart channels that share a parameter name.

{
  "workspaceId": "$workspaceId",
  "parameterIds": ["$parameterId"]
}

Live valueType.name → snapshot type: num → numeric; int / bool → integer; str / ipaddr / macaddr / bigint / datetime / geo → string.

Create a chart report

Freeze the parameters with Freeze from live, put the returned snapshots in parameters, and add one chart series per parameter. This body uses the defaults of a new chart in Setup:

{
  "workspaceId": "$workspaceId",
  "title": "Boiler room temperatures",
  "parameters": [
    {
      "parameterId": "$parameterId",
      "sourceValueType": "num",
      "type": "numeric",
      "label": "Channel 1 · Sensor temperature",
      "units": "°C",
      "icon": null,
      "defaultColor": "blue",
      "bold": false,
      "italic": false,
      "zoneColors": []
    }
  ],
  "representations": {
    "chart": {
      "type": "chart",
      "parameters": [
        {
          "parameterId": "$parameterId",
          "type": "numeric",
          "opacity": 1,
          "showAs": "line",
          "decimalPlaces": 2,
          "scaleMultiplier": 1,
          "scaleShift": 0,
          "smallestGapSizeMs": 120000
        }
      ],
      "minimumPrecisionMs": 1000,
      "maximumPointsOnScreenPerParameter": 1000,
      "fullRangePointsForNavigationPerParameter": 1000,
      "focusAxisOnSeries": true,
      "realtimeUpdate": false,
      "showMinMaxPerParameter": false,
      "height": 280,
      "showTooltips": true,
      "chartDisplay": "movable",
      "navStrip": "movable",
      "legend": "interactive",
      "showComments": false
    }
  },
  "layout": { "type": "simple", "rows": [[{ "representation": "chart", "column": "full" }]] }
}

For several parameters, add one snapshot and one series for each. Open /workspace/$workspaceId/reports/$presetId with the returned ID.

Create temporary

report.preset.createTemporary backs Quick report in Setup → Parameters and in dashboards. Operator or higher. Up to 20 unique IDs; duplicates are dropped, and more unique IDs fail with report_preset_temporary_limit_exceeded. Missing and unsupported IDs are returned in skipped; when none remain, the call fails with report_preset_no_supported_parameters. The server builds the recipe: a chart of every kept parameter, time bars of the numeric ones, a table of every parameter, and a default range set by cadence (below), with comments, signing, snapshot sharing, and CSV export off. The preset is not in list until saveTemporary.

Time bars average each numeric parameter. Optional counterParameterIds names counters among parameterIds, and their bars show the per-interval difference (delta) instead. Other ids fail with report_preset_temporary_counter_not_requested. Non-numeric counters stay as they are. Counters are already in parameterIds, so they take no extra places under the cap.

Optional cadence sets the time bar interval: 1h (default) shows the last day with a precise table; 1d shows the last 31 days with one table row per day, so counters show their daily consumption.

{
  "workspaceId": "$workspaceId",
  "parameterIds": ["$powerParameterId", "$energyParameterId"],
  "counterParameterIds": ["$energyParameterId"],
  "cadence": "1d",
  "title": "Quick report"
}

Save temporary

report.preset.saveTemporary requires Editor access. It keeps the same ID. The input is id and the preset’s recipe as get returns it: title, description, parameters, representations, layout, defaultTimeRange, immutableTimeRange, allowAddComments, displayCommentsSummary, allowSigning, allowRender, exportToCsv, showEditButton and timezone. The input rejects the other fields of get (workspaceId, isTemporary, revision, createdAt, updatedAt). Without baseRevision, a retry after success returns the saved preset. With the revision you read as baseRevision, the save fails with setup_conflict if the preset changed since, including when it was saved meanwhile. A saved preset cannot become temporary again. update on a temporary preset fails with report_preset_temporary_update_forbidden.

Numeric snapshot

{
  "parameterId": "$parameterId",
  "sourceValueType": "num",
  "type": "numeric",
  "label": "Sensor temperature",
  "units": "°C",
  "icon": null,
  "defaultColor": "blue",
  "bold": false,
  "italic": false,
  "zoneColors": []
}

Integer snapshot

sourceValueType is int or bool.

{
  "parameterId": "$parameterId",
  "sourceValueType": "int",
  "type": "integer",
  "label": "Relay",
  "units": null,
  "icon": null,
  "defaultColor": "blue",
  "bold": false,
  "italic": false,
  "valueColors": {}
}

String snapshot

{
  "parameterId": "$parameterId",
  "sourceValueType": "str",
  "type": "string",
  "label": "Status",
  "units": null,
  "icon": null,
  "defaultColor": "blue",
  "bold": false,
  "italic": false
}

Chart series

Series type matches the snapshot type. A chart’s parameters holds one series object per parameter. The chart reference lists every value.

Numeric:

{
  "parameterId": "$parameterId",
  "type": "numeric",
  "opacity": 1,
  "showAs": "line",
  "decimalPlaces": 2,
  "scaleMultiplier": 1,
  "scaleShift": 0,
  "smallestGapSizeMs": 120000
}

The default smallestGapSizeMs is 120000. A missing-slot duration strictly greater than the threshold breaks the numeric line; 0 therefore breaks on every positive missing span.

Integer:

{
  "parameterId": "$parameterId",
  "type": "integer",
  "opacity": 1,
  "showAs": "filled-areas"
}

String:

{
  "parameterId": "$parameterId",
  "type": "string",
  "opacity": 1,
  "showAs": "vertical-line-on-change"
}

showComments: true on the chart shows comment stripes above the plot.

Table columns

Default columns of a new table, by snapshot type:

{ "parameterId": "$parameterId", "type": "numeric", "decimalPlaces": 2, "perCadenceValue": "latest", "totals": "none", "bgZoneColorOpacity": 0 }
{ "parameterId": "$parameterId", "type": "integer", "bgOpacity": {}, "totals": "none" }
{ "parameterId": "$parameterId", "type": "string", "totals": "none" }

The table reference lists every value.

Layout

layout is { "type": "simple", "rows": [...] }. Each row is an array of cells { "representation": "<key>", "column": "<width>" }, where <key> is a key of representations and <width> is full, 1/2, 1/3, or 1/4.

"layout": {
  "type": "simple",
  "rows": [
    [{ "representation": "chart", "column": "full" }],
    [{ "representation": "table", "column": "full" }]
  ]
}

Default time range values

Without these fields, create uses the last 7 days and timezone: "browser".

"defaultTimeRange": { "type": "last-days", "days": 7 }

"defaultTimeRange": { "type": "current", "segment": "day" }

segment: hour day week month year.

"defaultTimeRange": { "type": "from-to-now", "from": 1710000000000 }

"defaultTimeRange": { "type": "fixed", "from": 1710000000000, "to": 1710086400000 }

"defaultTimeRange": { "type": "full-range-to-now" }

"immutableTimeRange": true locks the window on the report page. "timezone" takes "browser" or an IANA name such as "Europe/Warsaw".

Update

update takes id and the fields to replace, for example { "id": "$presetId", "title": "Boiler room temperatures, line 1" }. Each field sent replaces the stored one whole: parameters, representations, and layout are not merged. update on a temporary preset fails with report_preset_temporary_update_forbidden.