Tags¶

Tags are essentially variables representing specific data coming from devices — for example temperature, humidity, voltage, current, liquid level in a tank, gas consumption, input/output states, or battery charge level.

They are the basic data element in the system, since all readings, alarms, and value presentations on synoptic screens and in reports refer to them.

Types of tags in the system¶

The DataPortal system offers several tag types, which differ in how the data is obtained, how it is stored, and how it is used. Below is a detailed description of each tag type.

Register¶

A tag of type Register represents a value read directly from a data source (telemetry device).

It is linked to a specific register of the device.
The data comes directly from communication with the device.
Such a value is updated according to the device's data transmission cycle.

Virtual¶

A Virtual tag is not associated with a device by default.

Its value can be entered manually.
Once assigned to a device, it works the same as a Register type tag, but its type formally remains "Virtual".
Useful in situations where you want to store or pass auxiliary data.

Calculated¶

A Calculated tag has a formula based on which its value is generated.

It contains calculation logic (a mathematical or logical formula).
It is saved to the database.
The save schedule depends on the configuration: it can be triggered periodically (timer) or when the input data changes.
Ideal for creating derived values, indicators, logical statuses, etc.

Local¶

A Local tag exists only on the visualization screen (SCADA).

It is not saved to the database.
It can serve as an auxiliary variable or a tag calculated in real time.
Its value is recalculated every 0.5 seconds.
Useful when fast, frequent data updates are needed only for visualization purposes.

Placeholders¶

A Placeholder is not a proper tag, although it can be created from the same dialog box in the editor as the other tag types.

It serves as a placeholder within the screen's structure.
It allows you to create screen templates or structures that will be filled with real tags at a later stage.
It has no value, does not collect data, and is not associated with a device.
It has a defined format, which enables correct validation when assigning the target, real tag.

Placeholder and tag groups¶

Placeholder and tag groups allow placeholders to be dynamically swapped for actual tags while the screen is running. To do this, you first need to define a group in which each placeholder has a corresponding tag assigned to it.

In run mode, a special script — triggered e.g. by a button — substitutes tags from the selected group in place of the placeholders. As a result, once the button is clicked, all values on the screen are automatically linked to the correct tags. Similarly, such a script can be attached to an element that opens another screen, so that it is loaded already with the full set of substituted tags.

More information on placeholders and groups can be found in the next chapter.

Creating tags¶

New tags can be created from several different places in the system: on the TAGS tab available in the Resources module, in the data source details on the TAGS tab, or from the function panel menus in screen edit mode.

Adding a tag from resource management¶

Click the New tag button in the add-resource menu visible in the top right corner in the Resources module, on the TAGS tab.
Enter the tag name - it cannot contain spaces or accented characters (e.g. Temp_chlodni).

Info

Each tag is uniquely identified within a data source – this means there cannot be two tags with the same name within the same source.
Enter the display name, which is user-friendly (e.g. Cold store temperature). It will be shown, among other places, in reports.
Optionally add a tag description, which will make it easier to identify.
Select the data source (and thus the device) the tag will be linked to.
Select the tag kind.
For a Register-type tag, select the register type – analog input, digital input, digital output, or a holding-type register.
Select additional parameters (such as data format, address, start bit, byte order, or bit range).
Optionally specify a unit of measure (e.g. °C, %, V).
Optionally set the scaling type, which lets you, for example, present measured values in % or convert e.g. mV to V. The system offers linear scaling — simply provide two raw values and the corresponding resulting values, displayed after scaling. Also set how the already-scaled value should be displayed.

Note

If you set scaling for a given tag, the database will not store the raw values, only the scaled ones.
Optionally set warning and alarm levels, exceeding which will generate the appropriate warning or alarm. Also specify the hysteresis, i.e. the minimum amount by which the parameter must return below (or above) the threshold for the system to consider the alarm state ended — this helps you avoid unwanted alarm "flickering" when values fluctuate.
Optionally enable notifications (if you have enabled alarming and defined warning/alarm thresholds) - select the appropriate notification template, previously defined in the notification Rules section. If a warning or alarm situation occurs, an SMS and/or e-mail will be sent to the relevant recipients, according to the options set in the selected rule.
Set the retention - the length of time the data for this tag is stored in the system.
Click the SAVE button to create the new tag.

Adding default tags¶

For each device type in the system, a set of default tags is defined, corresponding to the most commonly used parameters and operating states of the device.

If a device has an assigned data source, default tags can be added automatically from that source's details:

Go to the Resources module and open the Sources tab.
Click the selected data source to display its details.
Go to the TAGS tab.
Click the + button, then select the Add default tags command.
A dialog box will appear with information about adding default tags.
Clicking the info (i) icon will display the list of tags that will be created
(this list depends on the type of device associated with the source).
Click the ADD button to confirm the operation.

Once confirmed, all default tags will be automatically created and assigned to the given data source.

Tip

Adding default tags significantly speeds up system configuration and eliminates the need to manually create the most commonly used tags. If tags are created that turn out to be unnecessary, they can always be deleted.

Adding a tag from the screen editor¶

Go to screen edit mode.
From the menu on the right side of the editor, select the TAGS command.
In the tags panel, click the Create button visible in the top left corner of the tags panel.
Specify the parameters of the new tag, as described above.
Click the ACCEPT CHANGES button.

Adding calculated and virtual tags

Calculated tags and virtual tags can only be added to the system from the DataPortal Designer editor.

Tag properties¶

Each tag has a set of properties defining how it behaves and is displayed.

Last value¶

The last value section contains read-only fields:

Field	Description
Value	The tag's last read value along with its unit. Shows the current state of the variable.
Measurement time	The moment the device took the measurement (the time the data was generated at the source).
Database registration time (UTC)	The time at which the reading was saved in the system's database. May differ from the measurement time in the case of communication delays or a buffer data read.
Last value change (UTC)	The date and time the tag's value last changed in the database — updated only when the value actually changes.
Previous change (UTC)	The moment of the change prior to the current one; lets you track the dynamics of the changes.

Basic information¶

Field	Description
Name	The tag's unique name used in the system. Should be unambiguous and technically readable; no spaces, accented characters, or special characters.
Display name	A friendly name shown to the user on screens and in reports; can be more descriptive.
Description	Additional information about the tag's purpose or logic; helpful for documentation and teamwork.
Date added	The date and time the tag was created; a read-only field.
Project	The project the tag is assigned to (through the source); defines its context in the system.
Source	The data source the tag retrieves its value from; the tag is linked to the project through the source.
Kind	Specifies how the value is obtained: register (read from a source), virtual (no device, an auxiliary variable), or calculated (value from a formula/rule).
Type	The nature of the data retrieved from the device's register — can indicate a digital input/output, an analog input, or a holding-type register.
Format	The data format specifying how the value is interpreted (e.g. `BIT_I/O`, `UINT2`, `FLOAT8`).
Byte order	The arrangement of bytes when reading data (e.g. `HL`, `LH`).
Address	The register address in the device from which the value is read.
Start bit	The bit position within the register, if the tag reads a single bit.
Bit range	The number of consecutive bits read from the register; used for bit fields.
Units	The unit of measure of the displayed value (e.g. `°C`, `%`, `V`).
Retention period	The archiving period for the tag's data; once it passes, the data is deleted.

Value scaling¶

Field	Description
Linear value scaling	Specifies whether the tag should be linearly transformed according to a defined formula (value mapping).
Raw value 1	The first (lower) input value (from the device).
Raw value 2	The second (upper) input value (from the device).
Scaled value 1	The lower value after scaling — the result that should correspond to raw value 1.
Scaled value 2	The upper value after scaling — the result that should correspond to raw value 2.
Presentation after scaling	The display format of the scaled value (e.g. number of decimal places, rounding method, presentation style).

Linear scaling

When defining scaling, you don't need to select minimum and maximum values — you choose any two reference points that best describe the relationship between the raw value and the expected physical value. The system uses them to calculate a linear relationship (a straight line), so that every intermediate value is automatically converted according to the same rule.

Alarming¶

Field	Description
Alarming	Enables or disables the alarm function for this tag. When disabled — no events are generated.
HiHi alarm	Upper alarm threshold. The alarm is triggered when the value exceeds this level. Used for critical deviations.
Hi alarm	Upper warning threshold. An alarm triggered after this value is exceeded indicates a warning or serious deviation.
Lo alarm	Lower warning threshold. An alarm is generated when the value drops below this level.
LoLo alarm	Lower alarm threshold. Triggered when the value drops further below the Lo threshold.
Hysteresis	An additional margin that prevents an alarm from continuously triggering and clearing at the threshold boundary. The alarm only clears once the value returns to range, taking the hysteresis into account.
Auto-acknowledge	Specifies whether an alarm can be automatically marked as acknowledged, without manual user intervention.
Auto-acknowledge time	The number of seconds after an alarm occurs after which the system automatically marks it as acknowledged (provided auto-acknowledge is enabled).

Notifications¶

Field	Description
Notification	Specifies whether notifications (e.g. e-mail, SMS) should be sent for this tag when an alarm occurs.
Alarm priority	A numeric alarm priority indicating its significance. May affect the order in which alarms are handled or how they are presented in the system.
Notification rules	A list of rules assigned to the tag. Each rule defines the message content, the sending method (SMS, e-mail, etc.), and the recipients. Multiple rules can be assigned to a single tag, allowing it to generate different notifications depending on need.

Tag details¶

Clicking a selected tag in the tags table (Resources module, TAGS tab) opens a window presenting detailed information about the given tag. To make working with the data easier and keep it organized, the information is divided into several topic-based tabs:

INFO tab¶

The INFO tab contains the tag's key parameters, such as name, source linkage, format, address, units, scaling, and alarm and configuration settings. At the top, a section is displayed showing information about the tag's last read value, along with the exact date and time the value was read and saved in the system.

HISTORY tab¶

The HISTORY tab presents a table containing all recorded data for the selected variable. The table includes, among others, the following information:

data read time,
system registration time,
read value,
alarm state (OK, LoLo, Lo, Hi, HiHi),
data origin (e.g. event, buffer read, loss of communication),
data quality.

The user can filter the data by:

selected time range,
value range,
data origin,
data quality.

There is also an option to delete selected records from the history.

CONTROL tab¶

The CONTROL tab presents the history of all commands sent to executive devices using this tag. The table contains information that lets you trace when control actions were performed and with what result. The available columns include:

Timestamp – the moment the control command was sent to the device.
Date added – the time the command was registered in the system.
Value – the controlled value that was sent (e.g. 0/1 for digital outputs).
Status – the result of the control attempt:
- Delivered – the command was successfully delivered and executed,
- Failed – the command was not executed due to an error or lack of communication,
- In progress – the command has been sent and is awaiting confirmation of execution,
- Pending – the command has been created and is waiting to be sent.

The table can be filtered using the available filtering options, which makes it easier to analyze specific periods or control results.

CHART tab¶

The CHART tab presents a graphical history of changes in the tag's value over a selected time range. It allows you to quickly visually analyze trends, deviations, and anomalies that may be hard to notice in a data table.

The chart provides:

value trend line – shows changes in the tag's value over time,
time axis – presents successive data registration moments,
value axis – shows the read values,
time range bar (bottom slider) – lets you smoothly narrow or expand the period being analyzed.

The filter makes it easy to narrow the chart down to the range the user is interested in, without having to manually scroll through the data. This allows for quick analysis of both short-lived events and long-term trends.

ALARMS tab¶

The ALARMS tab presents the history of alarm events related to the selected tag. It allows for a detailed analysis of when alarms were generated, acknowledged, and what their nature was.

The table includes the following columns:

Created – the date and time the alarm occurred, i.e. the moment the alarm threshold was exceeded.
Acknowledged – the date and time the alarm was acknowledged (manually or automatically, if auto-acknowledge is enabled).
Alarm – the alarm type corresponding to the exceeded threshold (OK, LoLo, Lo, Hi, HiHi).
Message – the content of the message associated with the alarm (if applicable).

The tab also allows filtering events using the available FILTER panel, which lets you limit the view to alarms from a specific period or of a selected type.

Editing a tag¶

The tag configuration can be edited from the tag details window. To start editing, click the EDIT button located at the bottom of the window.

Only the information presented on the INFO tab can be modified — this is where all the editable tag parameters are found. The remaining tabs (HISTORY, CONTROL, CHART, ALARMS) are purely informational and present data collected automatically by the system, without the possibility of user intervention.

After making changes, click the SAVE button to confirm and save the new tag configuration.

Deleting tags¶

Deleting a tag permanently deletes all its historical values, alarms, and links to screens. Before confirming the operation, the system displays a warning dialog box.

To delete a tag:

Go to the Resources module.
Select it from the list on the TAGS tab.
In the tag details window, click the DELETE button.
Confirm the operation.

Note

Once a tag is deleted, its data cannot be restored.