About the Historian module
The Tag Historian module offers a comprehensive solution for managing time-series data collection and storage. It enables storing tag values and timestamps in SQL or third-party time-series databases without programming requirements. The module's standard configuration tools cater to most data logging needs, although users can incorporate custom procedures using Scripts (.NET) and Datasets (SQL).
As an essential component for handling historical data from industrial equipment and systems, the Historian module provides key benefits within the platform:
Data Collection
Real-time collection and storage of data from sensors, devices, and other sources enable comprehensive analysis.
Data Management
A secure, reliable, and scalable data storage infrastructure that handles large data volumes generated by industrial equipment and systems.
Data Analysis
Built-in analytics tools allow for complex data analysis, including visualization, trend analysis, and statistical evaluations.
Predictive Maintenance
Historical data analysis and pattern identification enable the prediction of equipment failures or malfunctions.
Process Optimization
Analyzing historical data helps pinpoint areas for improvement, such as identifying bottlenecks, reducing downtime, and enhancing equipment performance.
The Historian module significantly enhances the platform's functionality by providing users with essential tools for collecting, storing, and analyzing data from industrial equipment and systems. It leads to improved efficiency, increased productivity, and reduced downtime, resulting in a more profitable and sustainable industrial operation.
Purpose and Key Concepts
The purpose of the Historian module is to ensure that important process data is securely stored and easily accessible for analysis and decision-making. By collecting and storing time-series data, it enables organizations to monitor equipment performance, optimize processes, track trends, and improve overall efficiency.
In order to understand its configuration and execution, the following concepts are important:
Target Database
There are many options to define where the data should be archived. Ranging from traditional SQL databases to third-party products specifically designed to store long term time related values, usually called time-series databases or Historian tools.
Historian Table
HistorianTable is a logical organization to group Tags for historical archiving.
Each HistorianTable has a definition on which Target Database that group of Tags will be archived. Other common settings that applies to all tags in that group are also configured in the HistorianTable, such as when a new data shall be saved, or for how long the data shall be kept.
The HistorianTable is just a logical grouping to expedite and simplify the configuration, not necessarily it will correspond to a table in the Target Database; different targets have their own archiving structures.
Historian Tag
The variables grouped in a HistorianTable are typically Tags defined in this platform. But it is also possible to include dynamic references to external data, using the TagProvider functionality.
Therefore, across the documentation, the generic term Historical Item refers to any value that is included in a HistorianTable to be archived, whatever is an internal Tag or an external data reference.
How the Historian module works
Archiving Process
The module Historian process to archive data is composed of 3 steps:
Step 1
An Event starts the request to archive the value of a group of variables.
There are two types of events (Trigger or TagChange). The events that start the archiving are configured in the Historian Tables section, and the variables that are archived in response to that event are configured in the Historian Tags section.
Step 2
The Historian archives the values in the Target database.
The Target Database can be a SQL Database or a third package, like Canary, InfluxDB, configured to act as a historian.
Step 3
If Store and Forward are enabled, the data synchronization is executed.
With this option, if the Target Database is unavailable, the data is stored in a local database and sent to the target when it becomes available.
Events to start the Archiving
Trigger
The Trigger can be a Tag Value, a Tag Property, or any object from the runtime namespace (e.g., server.minute will save data every minute). When a value change in the object is detected, the archive request event is generated.
Only Tags of server domains or objects residing in server-side namespaces can be used as Triggers since the Historian process runs on the Server computer.
The Trigger is configured in the Historian Table. All tags and objects connected to that HistorianTable will be requested to be archived, regardless of having or not a new value.
Tag Change
The Tag Change is a checkbox on the TableHistorian configuration.
When enabling the Tag Change checkbox, the Historian process will verify all tags connected to that Historian Table. When the tag has a new value, the archive request event is generated.
The request to archive will be generated only for the Tag with a new value. But, according to the Historian Target Database, only the tag or all tags in the group with be archived. Further information on that is included in the next section of this page.
Detailed execution description
The child page Arching Process has a detailed description of this process, including the exact schemas used for the database.
Configuring the Historian module
Configuration Workflow
The typical configuration workflow for the Historian Module has the following sequence:
| Historian Module Configuration Workflow | ||
|---|---|---|
| Action | Where | Comments |
| Define the default TagHistorian SQL Database | Historian → TargetDB | By default, TagHistorian maps to a SQLite database named the same as the Project Name. Modify it as needed. |
| If using Canary, modify the default target to the the Canary Historian | Historian → TargetDB | If using Canary, a connection with the local embedded Canary Historian is already included in new project. Just use that connection, or modify it willing to connect an external Canary System instead. |
| If necessary, add other Target Databases | Historian → TargetDB | If archiving or retrieving data from other Historian tools is necessary, such as InfluxDB or OSIsoft PI, add the connection in the Tag Providers, making sure to setup the "Historian Provider" checkbox. |
| Create and Edit HistorianTables | Historian → Tables | Add or modify HistorianTables, organizing how the Tags will be grouped for archiving and the Target Databases. |
| Add Tags to the HistorianTables | Historian → Tags | Connect Tags to the Historian tables. Either by typing, browsing, pasting or any of the available import methods. |
Default Target Database
By default, when a new project is created, the TagHistorian is defined to use the built-in embedded SQLite database, as defined in the Datasets module.
The Historian Target Database can be selected among the following options:
| Historian Database Options | |
|---|---|
| Target Database | Description |
| SQL Database | Any SQL style database, defined in the object TagHistorian on Datasets → DBs. |
| Canary Historian | Embedded CabaryLabs engine included in the framework, or connection with external Canary systems. |
| TagProvider Historian (InfluxDB, OSIsoft PI) | Using TagProvider, connect with third-party products that can act as native, fully integrated historian repositories. In addition to current interfaces, additional products can be easily added using the driver toolkit. |
The SQLite database may be used for databases up to around 10GB. If the amount of tags and the save interval is expected to create more than that, it is recommended to use another SQL database for the Tag Historian or the Canary Historian, or any of the available TagProvider Historian target.
To define another SQL Database to the TagHistorian connection, refer to the Dataset module configuration. <<<<<<. link >>>>>>>
To define other Tag Provider Historian targets, refer to the Tag Provider configuration. <<<< link >>>>>>
Configuring Historian Tables
By default, there is one HistorianTable created using Dataset-TagHistorian SQL as the Target Database, and if Canary Historian is enabled, another HistorianTable using Canary target.
The settings on the HistorianTable provide rules for saving the tags connected with HistorianTable. You can set a trigger that determine when tags will be saved — a time deadband that defines the minimum interval between saves, and a lifetime value that determines how long the saved tag values will be retained. According to the target database selected, some options may not be available.
It is a good practice to store only the data that is necessary, and with the time frequency that your process requires. Using features as headbands, OnTagChange or Trigger events, you organize your storage to save what is needed, without overload the system or slowing the data recovery.
HistorianTable configuration fields
New HistorianTables can be create with the NEW button, on Tags → Historian, or editing the table on Tags → HistorianTables.
To modify History Tables, on Tags → Historian, select the Table in the ComboBox and Config button, or editing the datagrid on Tags → HistorianTables.
Either using the Dialog view or datagrid view, the HistorianTable has the following configuration fields:
HistorianTable Configuration Properties | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Field | Description | ||||||||||||
Target | Defines the Historian Target Database. By default, SQL or Canary, or other TagProvider Historian connections. Historian Target Database According to the Target Database selected in this field, some other fields on the configuration may be disabled | ||||||||||||
Table Name | Name of the HistorianTable object. For SQL databases, this name is also the table name inside the SQL DB. For other databases, this name is used as a logical grouping name.. | ||||||||||||
Auto Create | When checked, Historian module will check if this table is already created in your SQL DB. If not, a new one will be created. | ||||||||||||
Save on Change | When checked, whenever your Tags value has changed, the event to archive the tag is generated. | ||||||||||||
Trigger | Here you can define the event that triggers the archiving of all the tags in the HistorianTable group to the database. The trigger can be any tag, or any object or property from the objects namespaces. For example When you click on "…" elypses button, a window will appear listing your Tags, Objects and Properties, allowing to select which one will act as a Trigger. | ||||||||||||
TimeDeadband | Enter the minimum logging interval. You must define in this format HH:MM:SS:MS (Hours, minutes, seconds, milliseconds). If left with zeros, this setting is not used. This is how long the system must wait after storing one value of a tag, before storing a new value. This field is used in conjunction with SaveOnChange option to avoid creating too many records in the database. For example Consider that you have a 5 seconds Deadband, the Deadband count will start when your Tag value changes. When Deadband count starts, any changes in Tag value in this range will not be saved on your DB if the time dead-end has not elapsed yet.. Your Tag’s value will only be saved in DB after TimeDeadband ends.
| ||||||||||||
Life Time | Here you can set in days how long the records will be stay on the Target Database. Every day, if the Historian Modules find data on the HistorianTables older than the lifetime, that data is automatically deleted. If its the value is 0 or blank, no automatic data deletion is executed. Data is no longer automatically deleted. | ||||||||||||
Save Quality | When checked, a column in your SQL DB store the Quality property of the Tag argon with the value. The quality level defines how much reliable is the Tag value and it follows the OPC standard specification. | ||||||||||||
Normalized | When checked, uses the Normalize table schema for SQL database, or the Standard schema otherwise. For more information on SQL database schemes refer to Archiving Process. | ||||||||||||
Value Columns Type | Select the Type for Value Columns used to store the tag values in the SQL database. This field can be edited ONLY when first creating the HistorianTable Options:
| ||||||||||||
GetSamples Method | Name of a method defined on Script → Class to allow customization when retrieving data from this tables. | ||||||||||||
Description | Description for this HistorianTable object. | ||||||||||||
Adding Tags for Data Logging
After configuring the HistorianTables, or just keeping the predefined ones, the next step is to list the tags to be archived in connection with those HistorianTables.
- Go to Tags → Historian.
- Type or select tags in the TagName column, or copy and paste tags from Tags → Objects.
Configure any required additional fields.
- Only the TagName and TableName fields are mandatory.
HistorianItem Configuration Properties | |
|---|---|
Field / Column | Description |
TagName | Enter a tag name or click "..." to select the tag for historian archiving. |
DeadBand | When using the SaveOnChange option in the HistorianTable, the DeadBand is how much the value must change (in Units) in order to the system store the value. |
Deviation | This value can override the Time Deadband logging interval. If the tag changes more than the Deviation value, the event to archive the tag is generated, even the deadband specified in TimeDeadBand has not elapsed yet. |
RateOfChange | This value can overrides the Time Deadband logging interval. If the Rate of Change of that is higher than this value, the event to archive the tag is generated, even the deadband specified in TimeDeadBand has not elapsed yet. The Rate of Change of a tag, is the difference on consecutive value changes, divided by the time in seconds between the changes. |
HistorianTable | Select the HistoranTable that this tag will be connected with. |
Working with the Historian
Runtime Execution
When the Project runs, the Module Historian runs in an isolated process on the Server Computer.
The main procedures executed by the module include:
Check if a request to archive from a HistorianTable was generated (by the Trigger or OnTagChange events).
Archive the Data as needed.
Synchronize with remote archives if store and forward or redundancy is enabled.
Reply to requests from Displays and Scripts on querying the archived data.
Those procedures as described in detail in the section Archiving Process.
On this page, we have covered the essentials of the Historian module, which provides a comprehensive solution for managing time-related data in industrial equipment and systems. To further enhance your understanding and optimize the use of this module, we recommend exploring the following sections:
Integration with Other Modules
You can learn how to seamlessly integrate the Historian module with other platform modules, such as the Security, Scripts, Displays, or Alarm module, to create a robust, cohesive, and efficient system tailored to your needs.
You can easily use the information from the historian archives in other modules, like creating TrendChart plots, or using in calculation scripts.
The page Integration with Other Modules presents information on that integration.
See Historian modules integrations.
Advanced Features and Options
Dive deeper into the Historian module's advanced features and options, such as data compression, data aggregation, and custom data queries. Discover how these features can help you unlock the full potential of your data analysis and process optimization.
See Historian advanced features.
Troubleshooting and Common Issues
You'll be able to familiarize yourself with common problems that may arise when using the Historian module and learn effective troubleshooting techniques to resolve these problems quickly and efficiently.
See Historian troubleshooting.
Diagnostics information about the Module execution is located in the section Historian Diagnostics.
Best Practices and Recommendations
Benefit from the knowledge of experts and experienced users by following our curated list of best practices and recommendations. These guidelines will help you ensure the successful implementation of the Historian module and maximize its impact on your industrial operations.
See Historian best practices and recommendations.
By exploring these sections, you will gain a deeper understanding of the Historian module's capabilities and learn how to leverage its full potential to improve your industrial processes, increase efficiency, and drive sustainable growth.
The Historian Namespace
The Historian namespace exposes properties and methods of the .NET objects used by the Tag Historian Module execution.
This section describes only some commonly used properties.
Examples of Tag Runtime Properties on Historian | ||
|---|---|---|
Property | Type | Description |
| Boolean | Flag indicating if Tag is confirmed in a Historian Table. |
| String | HistorianTable related to this tag. Usage: |
| Object | Entry point to access the Historian Item settings connect with this tag. |
Historian Module properties examples | ||
|---|---|---|
Property | Type | Description |
| Boolean | Flag indicating if the Module Historian has started. |
| String | Message OK or error when initiating the Module. |
| Boolean | When enabled, temporary binary files are created on the server computer in order to optimize the performance of the TrendChart object requesting large amounts of data. |
See Namespaces Reference for the complete list of properties and available methods.
In this section...