Versions Compared

Old Version 148

changes.mady.by.user Support

Saved on

compared with

New Version Current

changes.mady.by.user Paulo Tsuchiya

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


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

Module

Image Added

The Historian module Module enables the storage of tag values and their corresponding timestamps in SQL databases or third-party time-series databases. This module is designed to streamline the collection and storage of data in its time context. 

The Historian module Module provides an out-of-the-box solution for archiving historical data without programming requirements. Although it is possible to include custom data logging procedures can be included in your solution using Scripts (.NET programming) and Datasets (SQL storage), the standard configuration tools of the Historian module Module can fulfill most typical data logging needs. 

On this page:

Table of Contents
maxLevel3
minLevel2
stylenone

Purpose and

Key Concepts

Configuration of the Historian module is accomplished through the following sections: Target Database, Historian Table, and Historian Tag.

TargetDB

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 The TargetBD defines the database where variables will be archived or read to be used in for charts and calculations. The Target Database can be any SQL Database or, using the TagProvider Extensibility, it can also use third-party products designed to store long-term time-related values, known as time-series databases or Historian tools. The configuration of the Target Database is on the Solution Explorer, at Historian → TargetDBs.

HistorianTable

The HistorianTable is a logical organization that groups Tags for historical archiving. Each Historian Table has a definition of which Target Database the group of Tags will be archived. You can also configure other standard settings that apply to all tags in that group in the Historian Table, such as when to save new data or how long to keep the data. The configuration of the Historian Tables is on the Solution Explorer, at Historian → Historian Tables.

HistorianTag

The HistorianTag refers to any value contained in a Historian Table to be archived, whether an internal Tag or an external data reference. These variables are typically Tags defined in this platform, but you can also include dynamic references to external data using the TagProvider functionality. The configuration of Historian Tags can be found in the Solution Explorer, under the section Historian → Historian Tags.

Understanding the Historian module

AnchorArchivingProcessArchivingProcessArchiving Process Overview

The Historian module has a three-step archiving process:

  1. An event triggers the request to archive a group of values. There are two types of events (Trigger or TagChange), which are configured in a Historian Table.

  2. The Historian archives the values in the Target database. The Target Database can be a SQL Database or a TagProvider that is configured to act as a historian.

  3. If Store and Forward is enabled, the data synchronization is executed. This option stores data in a local database if the Target Database is not available, and sends it to the target when it becomes available.

The archiving process considers two types of archiving events:

  • Trigger: The Trigger can be a Tag Value, Tag Property, or any object from the runtime namespace (e.g., server.minute). When a value change is detected in the object, 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. Enabling this checkbox allows the Historian process to 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 for the Tag that has a new value. However, according to the Historian Target Database, only the tag or all tags in the group will be archived. Further information on this is included in the next section of this page.

For a more detailed Historian execution explanation, check Archiving process.

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 

Configuring the Historian module

Configuration Workflow 

The typical configuration workflow for the Historian Module has the following sequence:

Historian module configuration workflowActionWhere 

Comments

Define the default TagHistorian  SQL Database

Historian

→ TargetDBs

/ Storage Location

By default, TagHistorian maps to a SQLite database named and located

equal

the same as the Solution

itslef

itself, followed by the proper FileExtension.

You're able to change it as needed

Learn more at Historian Storage Locations.

If using Canary, modify the default target to the

 the

Canary Historian

Historian

→ TargetDBs

/ Storage Location

If using Canary, a connection with the local embedded Canary Historian is already included in the new solution.

Just

You can use that connection

,

or modify it

willing

to connect to an external Canary System

instead

. Learn more at Historian Storage Locations.

If necessary, add other Target Databases

Historian

→ TargetDBs

/ Storage Location

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 mark 

.  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

Historian tables

HistorianTables. Either by typing, browsing, pasting or any of the available import methods. Learn more at Historian Tags.

Default

TargetDB

Storage Location

When creating you create a new solution, the TagHistorian is set by default to use default database (Dataset.DB.TagHistorian) uses the embedded SQLite database provided in the Datasets module. The Historian Target Database can be chosen from a range of options, including selecting another SQL database for the Tag Historian, the 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 ExternalTags Historian targets.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

Historian Database options

Target Database 

Description 

SQL Database

Any SQL style database, defined in the object TagHistorian on Datasets → DBs.

Canary Historian

Embedded CanaryLabs engine included in the framework, or connection with external Canary systems.

ExternalTags Historian (InfluxDB, OSIsoft PI)

The ExternalTags feature allows for seamless integration

with third-party products, which can act as native and fully integrated historian repositories. This feature

provides not only

enables you to use current interfaces

but also allows for

or additional products

to

, which can be

easily

incorporated using the driver toolkit.

The SQLite database is suitable for databases up to around 10GB in size. If the number of tags and the save interval are expected to exceed this limit, it is recommended to use another SQL database for the Tag Historian, the Canary Historian, or any of the available ExternalTags Historian targets. It is advisable to select an alternative database option in cases where a solution is expected to create more tags or require frequent saving intervals that exceed the capabilities of the embedded SQLite database.

To configure a different SQL Database for the TagHistorian connection, please refer to the Dataset module configuration.

For other ExternalTags Historian targets, please refer to the ExternalTags configuration to define and configure their use.

Configuring HistorianTables

The Historian module creates a default HistorianTable using Dataset-TagHistorian SQL as the Target Database, with an additional HistorianTable being created if the Canary Historian is enabled. This setup offers a range of flexible options to choose from when selecting and configuring the target database for your solution's specific needs.

The HistorianTable settings allow you to define rules for saving the tags connected with it. You can set triggers such as a time deadband, specifying the minimum interval between saves, and a lifetime value, determining how long saved tag values will be retained. Note that certain options may be unavailable depending on the target database selected, so it's important to carefully consider your options.

Storing only the necessary data at the required frequency is a good practice to follow. You can use features such as deadbands, OnTagChange or Trigger events to organize your storage and save only what's required without overloading the system or slowing down data recovery.

HistorianTable configuration fields

New HistorianTables can be create with the NEW button, on  Historian → Historian Tags, or editing the table on Historian → Historian Tables.

To modify History Tables, on Historian  → Historian Tags, select the Table in the ComboBox and Config button, or editing the datagrid on Historian → Historian Tables.

Either using the Dialog view or datagrid view, the HistorianTable has the following configuration fields:

HistorianTable configuration properties

Field

Description

TargetDB

Defines the Historian TargetDB. By default, SQL. Can only be changed while creating the HistorianTable.

According to the Target option, 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.

When you click on "…" ellipses button, a window will appear listing your Tags, Objects and Properties, allowing to select which one will act as a Trigger.

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.

Image Added


When the Solution runs, the Historian Module operates in an isolated process on the server computer.

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.

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.

Tag's valueCurrent TimeWill be saved on DB?512:05:05:00Yes2012:05:07:00No2512:05:10:00Yes

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:

  • 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 Historian → Historian Tags.

  • Type or select tags in the TagName column, or copy and paste tags from Unified Namespace → Tags.

  • Configure any required additional fields.

  • Only the TagName and TableName fields are mandatory.

Image Removed

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. 

DeviationDeadBandType

  • Absolute
  • Percentage

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 module

Runtime execution

When the Solution runs, the Module Historian runs in an isolated process on the Server Computer. 

The main procedures executed by the module include:

  • Check Checking if a request to archive store 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 procedures as described in detail in the Archiving Process page.

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:

Monitoring Historian

It allows monitor and managing historical data storage. This functionality provides a clear view of the data and facilitates the analysis and optimization of system performance. For a comprehensive understanding, see the Monitoring HistorianTables. (Go to Historian → Historian Tables)

Displaying TrendCharts


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 ControlIt allows the visualization of trend charts for analysis and comparison of historical and real-time data. This functionality makes it easy to identify patterns and trends in system performance. For detailed information, see the Displaying TrendCharts.

Querying Data on Scripts

It This enables the querying and retrieving of data from variables and historical tables through scripts. This functionality empowers the creation of custom logic and solution-specific analysis. For a comprehensive understanding, refer to the Querying Data on 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

The Historian Namespace exposes properties and methods from the .NET objects used by the 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
BestPractices
BestPractices
Best Practices and Troubleshooting

Common Issues and Solutions

Data Not Being Stored

Check the HistorianTable

Troubleshooting and Best Practices

Table of Contents
maxLevel4
minLevel3
include#

Troubleshooting and Common #Issues

The Historian module may encounter some issues in its operation. Here are some common issues and their solutions:

#Data not being archived

Check the Historian Table configuration, Trigger or TagChange settings, and Target Database. Ensure the settings are correctly set up, and the database connection is valid.

#Incomplete

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

Store and Forward

not working

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

Database Connection Error

Check the database connection settings and ensure that the database is reachable.

Best Practices and

#Recommendations

Recommendations

To ensure the smooth operation of the Historian module, follow these best practices:

#Use descriptive names

Use Descriptive Names for Historian

objects

Objects

Use clear and descriptive names for Historian TablesHistorianTables, tags, and other related objects.

#Optimize data retrieval

Optimize Data Retrieval

Optimize data retrieval by enabling caching when working with large datasets.

#Ensure data integrity

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

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 yours historians configurations

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

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.

Historian Runtime Attributes

The Historian namespace exposes properties and methods of the .NET objects used by the Tag Historian Module execution.

For general information on namespace and object concepts, go to the section Objects and Namespaces.

This section describes only some commonly used properties. See Namespaces Reference for the complete list of properties and available methods.

Examples of Historian properties 

Property

Type

Description

To access the property on CodeBehind

IsStarted

Boolean

This is a Boolean flag that indicates whether the Module Historian has started. If the flag is set to "true," it means that the Module Historian is up and running, actively archiving data according to the configured Historian Tables. If the flag is set to "false," the Module Historian has not yet started, and no data archiving is taking place.

Historian.IsStarted

OpenStatusMessage

String

This is a string that displays a message indicating the success or failure when initiating the Module Historian. If the Module Historian starts successfully, the message will typically show "OK" or a similar confirmation. If there is an error during the initiation process, the message will display an error description to help diagnose and troubleshoot the issue.

Historian.OpenStatusMessage

EnableCache

Boolean

This is a Boolean flag that, when enabled, allows the creation of temporary binary files on the server computer to optimize the performance of the TrendChart object when requesting large amounts of data. With caching enabled, the system can quickly retrieve the necessary data for the TrendChart object without causing significant delays or performance issues. By setting this flag to "true," users can benefit from improved performance and responsiveness when working with large datasets in the TrendChart object.

Historian.EnableCache

In this section:

Page Tree
root@self
spacesV10

...