| HTML |
|---|
<style>
.text-span-6 {
background-image: linear-gradient(99deg, rgba(170, 163, 239, .5), rgba(125, 203, 207, .5));
border-radius: 50px;
padding-left: 15px;
padding-right: 15px;
}
#title-text {
display: none;
}
.panelgradient {
background-image: linear-gradient(180deg, #d5def0, whitesmoke);
border-radius: 8px;
flex-direction: column;
justify-content: center;
align-items: center;
padding: 4rem;
display: flex;
position: relative;
}
</style>
<div class ="panelgradient">
<h1 style="text-align: center;">Historian <br> (Time-Series Data)</h1>
</div> |
Introduction to the Historian Module
The Historian Module enables the storage of
About the Historian Module
The Tag Historian module provides several tools to manage data collection and storage as time related data. It offers a robust solution for storing tag values and their corresponding timestamps in SQL databases or third-party time-series databases. For many industrial processes Data Logging is essential, collecting and storing data in context of its time frame. Typically, users utilize this data to create trend charts, perform data analytics, monitor performance, ensure regulatory compliance, manage operations, and control processes.This module is designed to streamline the collection and storage of data in its time context.
The Historian Module This module provides an out-of-the-box solution for archiving historical data without programming requirements. It provides users with flexibility in terms of storage options and advanced features. While you can include additional Although custom data logging procedures can be included in your project solution using Scripts (.NET programming) and Datasets (SQL storage), the Historian module's standard configuration tools of the Historian Module can fulfill most typical data logging requirementsneeds.
On this page:
| Table of Contents | ||||||
|---|---|---|---|---|---|---|
|
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.
TrendChart and Scripts Integration
When creating TrendCharts on Displays, using tags defined in the Tag Historian Module, the historical database will be automatically queried. There is no configuration necessary in order to allow to plat the historian data, it is a built-in feature in the platform framework.
| Info |
|---|
| See Configuring the Trend Window for more information. |
In the same way, the several methods on Scripts or Reports that use historical data, using the logical organization of the HistorianTables, despite on which repository the data will be last archived.
Data Storage Abstraction layer
The ability to group tags to archive concurrently to various Target Databases, combined with the seamless integration with TrendCharts and other modules when retrieving the data, makes this platform perfect to act as Data Storage Abstraction Layer for industrial applications.
Using its concept, you can create flexible applications for Presentation Layer, User Interface Graphics, Scripting and Data Analytics, that are agnostic to where the underlining data is last stored.
It allows to easily combine distinct data sources, with standard data access interfaces, and minimal effort when the data sources are updated or migrated.
How the Historian Module Works
Archiving Process
The Module Historian process to archive data is composed by 3 steps:
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 starts the archiving are configured in the Historian Tables section, the variables that are archived in response of that event are configured in the Historian tags section.
2) The Historian archives the values in the Target database.
The Target Database can be a SQL Database or a third packages, like Canary, InfluxDB, configured to act as historian.
3) If Store and Forward is enabled, the data synchronization is executed.
and Terms
HistorianTag
Tags whose values are stored in a HistorianTable, including dynamic references to external data.
HistorianTables
Groups Tags for historical archiving, defining settings for storage and retention.
StorageLocation
Defines where historian variables will be archived or read for charts and calculations.
Understanding the Historian Module
Module Features
- Embedded Canary Historian includes 100 free Canary historian tags with any license.
- The Historian Module works with the industry's major players (OSISoftPI, InfluxDB).
- Store and Forward function ensures your data will not be lost if the database is unavailable.
- Universal Time and Daylight Saving
Technical Overview
- You can define a Tag representing any data point you want to track over time.
- You can then add this Tag to a HistorianTable and configure settings like:
- How often to sample and store data (e.g., every second, every minute)
- Conditions to store the data (e.g., only when the value changes)
- Data retention policies (e.g., keep data for 1 year)
- The HistorianTable is associated with a StorageLocation, determining where the data will reside.
- The Historian Module regularly samples the tag's value and writes the time-series data to the designated StorageLocation according to the settings in the Historian Table.
Configuring the Historian Module
Configuration Workflow
Historian Module Configuration Workflow | ||
|---|---|---|
Action | Where | |
With this option, if the Target Database is not available, 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 domain Server 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 HistorianTable. 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 check-box on the TableHistorian configuration.
When enabling the Tag Change checkbox, the Historian process will verify all tags connected to that HistorianTable. When the tag has a new value, the archive request event is generated.
The request to archive will be generated only to the Tag that has a new value. But, according the Historian Target Database, only the tag or all tags in the group with be archived. Further information on that is included on the next section of this page.
Detailed execution description
The child page Arching Process, has the 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:
Comments | |
|---|---|
Define the default TagHistorian SQL Database | Historian |
/ Storage Location | By default, TagHistorian maps to a SQLite database named and located the same as the |
Solution itself, followed by the proper FileExtension. Learn more at Historian Storage Locations. |
If using Canary, modify the default target to the |
Canary Historian | Historian |
/ Storage Location | If using Canary, a connection with the local embedded Canary Historian is already included in the new |
solution. |
You can use that connection |
or modify it |
to connect to an external Canary System |
. Learn more at Historian Storage Locations. | |
If necessary, add other Target Databases | Historian |
/ Storage Location | If archiving or retrieving data from other Historian tools is necessary, |
add the connection in the Tag Providers |
. Mark the "Set as Historian Server" checkbox when creating the provider. Learn more at Historian Storage Locations. | |
Create and Edit HistorianTables | Historian / Historian |
Tables | Add or modify HistorianTables, organizing how the Tags will be grouped for archiving and the Target Databases. Learn more at Historian Tables. |
Add Tags to the HistorianTables | Historian / Historian |
Tags | Connect Tags to the |
HistorianTables. Either by typing, browsing, pasting or any of the available import methods. Learn more at Historian Tags. |
Default
Target DatabaseBy 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:
(InfluxDB, OSIsoft PI)
In addition to current interfaces, additional products can be easily added using the driver toolkit.
| Info |
|---|
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.
| Info | ||
|---|---|---|
| ||
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.
| Info | ||
|---|---|---|
| ||
| 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.
| Info | ||
|---|---|---|
| ||
| 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. |
Storage Location
When you create a new solution, the default database (Dataset.DB.TagHistorian) uses the embedded SQLite database provided in the Datasets Module. However, you can change the default option at any moment. Our platform lets you choose from various Historian options, including SQL databases, Canary Historian, or any available TagProvider powered by Historian tools. For a large quantity of tags, you can create HistorianTables to organize the storage into groups. Data is saved to a SQLite database by default. You can customize this to save in any other SQL database or external storage.
| Tip |
|---|
You can use multiple Historian system with the same solution. One, already pre-defined, is the platform's built-in Historian using SQL databases. Additionally, you can use other Historian engines to solution, using the TagProviders to Historian packages, or using Script extensions. |
The table below describes the options available.
Database Option | Description |
|---|---|
SQLDatabase | You can use any SQL-style database defined in the object HistorianTag available on Datasets / DBs. |
Canary Historian | The platform includes an embedded Canary Labs Historian, and you can also use it with external Canary systems. Read more information on the Canary Labs page. |
TagProviders for Historians (InfluxDB, others) | The TagProviders feature allows you to seamlessly integrate with third-party products, which can act as native and fully integrated historian repositories. This feature enables you to use current interfaces or additional products, which can be incorporated using the driver toolkit. See the list of Historian TagProvider at the page UNS TagProvider Connections. |
Custom | There is a programming Interface that allows a class within the Script Module to act as the Historian repository, the call to archive and retrieved data are directly to that Script Class, and your solution has the complete freedom on customizing the responses to those requests. |
Using SQLite or other SQL databases
By default, the SQLite is selected when creating new solution, but our built-in SQL Historian can work with any other SQL database.
See at Dataset Module configuration how to set a different SQL Database for the TagHistorian connection.
For other TagProvider Historian targets, please refer to the UNS TagProvider Connections configuration to define and configure their use.
Working with the Historian Module
Runtime Execution
You can control the Historian module execution while running your solution. To Run, Pause, or Stop the Historian module directly from the platform, go to Access Runtime / Runtime Diagnostics to control the module.
When the Solution runs, the Historian Module operates in an isolated process on the server computer. The main procedures executed by the module include:
- Checking if a request to store
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.
| Info |
|---|
| 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:
- Float (4 bytes) - Default option
- Double (8 bytes)
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 is running, the Module Historian runs in an isolated process at the Server Computer.
The main procedures executed by the module includes:
- Check if a request to archive from a HistorianTable was generated (by the Trigger or OnTagChange events).
- Archive Archiving the Data data as needed.
- Synchronize Synchronizing with remote archives , if store and forward or redundancy is enabled.
- Reply Replying to requests from Displays displays and Scripts scripts on querying the archived data.
Those procedure as described in detail in the section Archiving Process.
Integration with Other Modules
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
Advanced Features and Options
<<<< Starting doing the content HERE is this page, move to a child only if necessary)
Troubleshooting and Common Issues
| Info |
|---|
For deeper and advanced understanding of the execution see Historian Advanced Topics / Archiving Process |
Monitoring the Historian Module Execution
When the solution is in runtime, the Historian Monitor menu provides a way to monitor real-time information related to the Historian Module operation.
→ Read more about the Historian Monitor.
Displaying TrendCharts
It is possible to display charts to analyze and compare historical and real-time data.
That is accomplished on displays using the TrendChart Control.
Querying Data on Scripts
This enables querying and retrieving data from variables and historical tables through scripts.
That is accomplish by using directly the methods and properties available on the Historian Runtime Attributes.
Historian Advanced Topics
Archiving Process
The Archiving Process is the process of receiving new data from Tags and storing it in databases defined by the StorageLocation. You can define different configurations to trigger storing actions based on your needs and database restrictions.
→ Read more about at Archiving Process.
Historian Runtime Attributes
<brief description> and link to the page
Diagnostics information about the Module execution is located in the section Historian Diagnostics.
<<<<<rename the pages from Diagnostics to the new name
Best Practices and Recommendations
<<<< Starting doing the content HERE is this page, move to a child only if necessary)
<brief description> and link to the page
The Historian Namespace
The Historian namespace exposes properties and methods ofThe Historian Namespace exposes properties and methods from
the .NET objects used by
the Tagthe Historian Module execution.
You can use these properties and methods on your Displays or to create Scripts and Alarms.
→ Read more about Historian Runtime Attributes.
| Anchor | ||||
|---|---|---|---|---|
|
Common Issues and Solutions
Data Not Being Stored
Check the HistorianTable configuration, Trigger or TagChange settings, and Target Database. Ensure the settings are correctly set up, and the database connection is valid.
Incomplete data
Ensure that the Historian module is started (IsStarted flag) and the archiving process is functioning correctly. Check for any error messages in the OpenStatusMessage string.
#Slow data retrieval
Enable the caching feature (EnableCache) to optimize performance when requesting large amounts of data.
Store and Forward Not Working
Verify if the Store and Forward feature is enabled and configured correctly. Check the local database and target database connections.
Database Connection Error
Check the database connection settings and ensure that the database is reachable.
Best Practices and Recommendations
To ensure the smooth operation of the Historian module, follow these best practices:
Use Descriptive Names for Historian Objects
Use clear and descriptive names for HistorianTables, tags, and other related objects.
Optimize Data Retrieval
Optimize data retrieval by enabling caching when working with large datasets.
Ensure Data Integrity with Store and Forward
Use Store and Forward to ensure data integrity in case of temporary database connection issues.
Plan Your Data Storage Strategy
Determine how much data you want to store and for how long you want to store it. It is important to plan your data storage strategy in advance so that you can optimize the historian module for your specific requirements.
Document Your Historians Configurations
Document your historian module configuration to make it easier to manage and maintain. This includes documenting data sources, data types, sampling rates, storage options, and performance optimizations.
Use Security Best Practices
Protect the historian module from unauthorized access by implementing security best practices such as user authentication, access control, and data encryption.
In this section:
| Info |
|---|
| For general information on namespace and object concepts, go to the section Objects and Namespaces. |
This section describes only some commonly used properties.
Examples of Tag Runtime Properties on Historian
Property
Type
Description
HasHistorian
Boolean
Flag indicating if Tag is confirmed in a Historian Table.
Historian.HistorianTable
String
HistorianTable related to this tag. Usage: Tag.Test.Historian.HistorianTable.
Historian
Object
Entry point to access the Historian Item settings connect with this tag.
Historian Module properties examples
Property
Type
Description
IsStarted
Boolean
Flag indicating if the Module Historian has started.
OpenStatusMessage
String
Message OK or error when initiating the Module.
EnableCache
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.
| Tip |
|---|
See Namespaces Reference for the complete list of properties and available methods. |
| Page Tree | ||||
|---|---|---|---|---|
|
...