The Tag Historian module performs automated data logging of selected tags to SQL databases as well as other databases. You can use the Datasets module to store this data in SQL, but the Tag Historian module has a simplified configuration; the database tables are automatically created with a built-in connection to the trend charts.

The system can also use the information from the historian for .NET scripting. It can get the past values for tags and graphic displays, or it can export the data.

You can select any SQL database (such as Microsoft SQL Server, Oracle, MySQL, or any OLEDB or ODBC compliant database) to store the data. By default, FactoryStudio uses an embedded SQL database (TatsoftDB) that has a maximum capacity of 10 GB. 

When using the OSIsoft(tm) PI System, there is no need to do any Historian configuration to access the data stored in the PI System.




Selecting a Database

The database used to store the TagHistorian is defined in Edit > Datasets > DBs.

By default, when a new project is created, the TagHistorian is defined to use the Tatsoft built-in embedded SQLite database. 

The SQLite database may be used for databases up to 10GB. If the amount of tags and the save interval is expected to create more than 10GB, you should define another SQL database for the Tag Historian.

To define another database to store the Tag Historian, you need to create a new database connection and name it TagHistorian. The system does not allow duplicate names. You must first rename or delete the existing row that uses TagHistorian before you can create a new database connection. 



The Tag Historian Tables

Configuration 

By default, the tag historian database has one table configured. The table settings provide rules for saving each tag. 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. The table configuration is independent of the database selected to store the information.
If you want some tags to have different settings, such as different time deadbands, you should configure additional tables with the settings you need and assign tags to the appropriate tables. You can also edit the settings of the default table.
In general, you should not store more data than you need. Storing a large amount of data slows the recovery of that data. You should use triggers and deadbands that are as large as possible, to ensure you have the information you need and without overloading the system. 

To configure a tag historian table:

  • Go to Edit > Tags > Historian.
  • Do one of the following:
  • To edit an existing table, select it from the Historian table's drop-down list and click Config.
  • To create a new table, click New.

Enter or select information, as needed.

Option

Description

Database

Display-only name of the current tag historian database.

Table Name

Enter a name for the table in the database.

Auto Create

Select to have the system automatically create the table in the database.

Save on Change

Select to store data in the table (add a row) every time a tag changes that is associated with the table.

Trigger

Use to store data in the table every time a tag or tag property changes. With the Save on Change option, the system stores data in the table when either the tag value changes or the trigger value changes.

Time Deadband (Log TimeSpan)

Enter the minimum logging interval. This is how long the system must wait after storing the value of a tag and before storing a new value. Use with the Save on Change option to avoid creating too many records in the database.

Life Time

Number of days to retain the historian data. After that time, the older rows are automatically deleted from the database. To never delete data, leave this field blank or enter 0 (zero).

Save Quality

Enable or disable the quality of the tag to be stored on the historian table

NormalizedEnable or disable to configure the schema to be used on the historian table
GetSamplesMethodUse to configure a Script > Class method to customize the data retrieved from the historian table

Description

Brief description of the historian table


Using the OSIsoft™ PI System

The system can seamlessly use the OSIsoft PI System as the historian provider. In this situation, it is not necessary define any Historian configuration. If the tag is mapped to a OSIsoft PI point, the system will automatically call the PI Server to get the data when trend charts are plotted trend or for any script or display methods that require historian information.

The system can work with both the PI System and the built-in historian at the same time. When historical information is requested for a point, either from trend charts or scripts, the system will first look for that information on the built-in historian module. If it is not available, it will try to find the data on the PI server. For information on connecting to the PI Systems, see Import Wizards.


The Tag Historian Tables Schemas

There are two different schemas for tag historian tables that are based on the configuration of the tables: the default schema and the normalized schema. Each schema is described below.

The Default Schema

The default historian tables contain the following columns:

  • ID - PK, BigInt (8 Bytes) - The primary key of the table used as reference by the system.
  • UTCTimeStamp_Ticks - BigInt (8 Bytes) - Date and time in Universal Time for that row in 64-bit .NET ticks. The value of this property is the number of 100-nanosecond (1/10th of a microsecond) intervals that have elapsed since 12:00 A.M., January 1, 0001. This is a new date/time standard used by the Microsoft .NET framework.
  • LogType - TinyInt (1 byte) - Auxiliary column to show when the row was inserted: 0=on startup, 1=normal logging, 2=on shutdown.
  • NotSync - Int (4 Bytes) - Auxiliary column to show if the data was synchronized or not when the Redundancy option is enabled. See Deploying Redundant Systems.
  • TagName - Float (8 Bytes) - Column automatically created using the name of each tag as the column title. It stores the data value using double precision.
  • _TagName_Q - Float (8 Bytes) - Column automatically created for the quality of the data for each tag, using the OPC quality specification.

Typically you can associate up to 200 tags with each historian table, but that number is dependent on how many columns your target database allows. The tags should be defined in the same table when they have similar storing rates and process dynamics because the entire row must be saved in order to save a tag in the table. 

The Normalized Schema

The Normalized tables have the following schema:

Table: TagsDictionary

  • ID - PK, BigInt (8 Bytes) - The primary key of the table used as a reference by the system.
  • TagName - NVarchar - The name of all the tags configured to "normalized" databases on the Historian.
  • NotSync - Int (4 Bytes) - Not used for this release. It was created for future changes and new features.

The system will automatically create four more tables as follows:

  • TableName_BIT
  • TableName_FLOAT
  • TableName_NTEXT
  • TableName_REAL

The schema for these table is:

  • ID - PK, BigInt (8 Bytes) - The primary key of the table used as a reference by the system.
  • UTCTimeStamp_Ticks - BigInt (8 Bytes) - Date and time in Universal Time for each row in 64-bit .NET ticks. The value of this property is the number of 100-nanosecond (1/10th of a microsecond) intervals that have elapsed since 12:00 A.M., January 1, 0001. This is a new date/time standard used by the Microsoft .NET framework.
  • ObjIndex - FK, Integer (4 Bytes) - Reference to the column ID on the TagsDictionary table
  • ObjValue - Can be Bit, Float, NText, or Real, depending on which table it is. Represents the value of the tag on the specified timestamp.
  • ObjQuality - TinyInt (1 Byte) - Represents the quality of the tag on the specified time, using the OPC quality specification.
  • NotSync - Int (4 Bytes) - Not used for this release. It was created for future changes and new features.

It's important to remember that the normalized database cannot be synchronized through the Redundancy option.



Adding Tags for Data Logging

After you configure your tables for the tag historian, you can configure the tags that will be logged.

To configure the tags for the tag historian:

  • Go to Edit > Tags > Historian.
  • You can copy and paste tags from the Objects tab.

  • Enter or select information, as needed.

    Column

    Description

    TagName

    Enter a tag name or click ... to select a tag.

    DeadBand

    When using the Save on Change option in the historian table, the DeadBand is how much the value must change (in Units) for the system to store the value in the historian.

    Deviation

    When using the Time DeadBand option in the historian table, the Deviation is how much the value must change (in Units) for the system to store the value in the historian. This value overrides the Time Deadband logging interval.

    RateOfChange

    When using the Time DeadBand option in the historian table, the RateOfChange is how much the value must change (in Units) by second, for the system to store the value in the historian. This value overrides the Time Deadband logging interval.

    HistorianTable

    Select the table that has the settings you want to use for when to save and how long to retain this tag's value.

    [Other columns]

    For definitions of other columns that are available in many tables, see Common Column Definitions.

  • Continue adding as many tags as you need.

Other settings:

Use Binary Cache: Select this option to store the tag historian data in binary blob columns instead of directly accessible values.

Changing this setting changes the storage format for future saves. Data in the previous format is not automatically converted. 



Visualizing Trend Charts

In order to visualize trend charts with historical information, you can use the built-in trend object on the displays or reports. See Configuring the Trend Window for more information.

Customizing Getting Samples

The trend chart object calls the Historian server to get the data to plot the charts. In some scenarios, you may want to override that configuration and define a .NET code to provide the values. This is used, for instance, to plot recipe calculated data, future data, data from other SQL tables, or any custom scenario.

The custom GetSamples method should be defined for any Script Class, and on Edit-Tags-Historian this method must be defined for the column GetSamplesMethod.

The prototype of the method is:
DataTable GetSamples(string[] tagNames, object startRange, object endRange) 

When creating tables that are used on time charts, the StartRange and EndRange are of the DateTimeOffset type. When getting data to X-Y charts, the Range arguments are double variables.

The Returned DataTable for time Charts shall have the columns:

  • DateTime: Date and time of the sample
  • TagName: The name of the tag is used as the FieldName to the column with Double values of the tag.
  • _TagName_Q: Optional column with the quality of the data

The Returned DataTable for XY Charts shall have the columns:

  • X: The name X is used for the column with Double values
  • TagName: The name of the tag is used as the FieldName to the column with Double values of the tag
  • _TagName_Q: Optional column with the quality of the data



The Historian Namespace

The Historian namespace has the properties and current status of the Historian server. The Historian.Table object has the list of Historian tables defined and their properties.

The following tag property is enabled if there is data logging for each tag.

Tag.tagname.Historian

  • No labels