Historian Module (Reference) provides comprehensive time-series data collection, storage, and retrieval capabilities for FrameworX solutions.
In
Overview
Links to Alarms Module tutorials, concepts, and how-to guides
- Building Solutions / Process Modules / Alarms Configuration (How-to Guide)
- Alarms Examples (How-To Guide)
this page:
Table of Contents maxLevel 2 minLevel 2 indent 10px exclude
Steps
Module Configuration
Configuration UI
→ Solution / Alarms / Items - tags and conditions to generate alarm. Include AlarmGroup for Ack/Log settings and AlarmArea for hierarchy.
→ Solution / Alarms / Groups - Collection of AlarmItems sharing properties such as AckRequired and LogEvents.
→ Solution / Alarms / Areas - Hierarchical grouping of AlarmGroups for better organization.
→ Solution / Alarms / Audit Trail - Logs changes and events when executing the solution, tracking who made changes and when. Useful for troubleshooting, analysis, and compliance.
Configuration Workflow
Historian Module Configuration Workflow
Action
Where
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 (Reference).
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 (Reference).
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 (Reference).
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 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. The table below describes the options available.
Storage Location
Description
SQLDatabase
You can use any SQL-style database defined in the object HistorianTag available on Datasets / DBs.
TagProviders for Historians (Canary, 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.
style none
Historian Module Configuration
Designer UI Section
Configuration Sections
| Section | Path | Purpose |
|---|---|---|
| Storage Locations | Historian → Storage Locations | Define data repositories |
| Historian Tables | Historian → Historian Tables | Configure archiving groups |
| Historian Tags | Historian → Historian Tags | Map tags to tables |
| Historian Monitor | Historian → Historian Monitor | Runtime status and trends |
Configuration Workflow
| Step | Action | Purpose |
|---|---|---|
| 1. Define Storage | Configure default database | Set primary repository |
| 2. Add Locations | Configure external historians | Multiple storage targets |
| 3. Create Tables | Define historian tables | Group tags logically |
| 4. Map Tags | Assign tags to tables | Configure collection |
| 5. Set Triggers | Configure archiving events | Control data collection |
Storage Options
SQL Databases
Default TagHistorian using embedded SQLite or external databases:
- SQLite (default, 10GB limit)
- SQL Server
- PostgreSQL
- Oracle
- MySQL
Tag Providers
External historian integration:
- CanaryLabs - Industrial historian
- InfluxDB - Time-series database
- GE Proficy - Enterprise historian
Custom Storage
Script Classes for specialized requirements:
- Cloud storage adapters
- Custom file formats
- API integrations
Runtime Architecture
Process Execution
The Historian Module runs as an isolated server process:
- Event detection and triggering
- Data archiving operations
- Store and Forward management
- Query response handling
- Synchronization tasks
Control Operations
Access via Runtime → Runtime Diagnostics:
- Run/Pause/Stop execution
- Monitor performance metrics
- View error messages
- Check module status
Historian Namespace
Access historian objects at runtime:
csharp
// Table properties
int rowCount = @Historian.Table.ProcessData.RowCount;
DateTime lastStore = @Historian.Table.ProcessData.LastStoredTimeStamp;
// Query methods
DataTable data = @Historian.Table.ProcessData.QueryData(startTime, endTime);
// Module control
bool isRunning = @Historian.IsStarted;
string status = @Historian.OpenStatusMessage;Key Concepts
Historian Tags
Individual data points mapped for archiving:
- Tag reference
- Deadband configuration
- Table assignment
- Collection parameters
Historian Tables
Logical grouping of tags:
- Storage location
- Trigger configuration
- Schema selection
- Retention policies
Storage Locations
Data repositories:
- Database connections
- External historians
- Store and Forward
- Custom implementations
Archiving Process
Data collection engine:
- Trigger evaluation
- Event detection
- Queue management
- Database writing
Archiving Methods
Trigger-Based
Event-driven collection:
- Time triggers (Server.Minute)
- Tag triggers (value change)
- Expression triggers
- Batch/process events
SaveOnChange
Continuous monitoring:
- Individual tag tracking
- Value change detection
- Deadband filtering
- Asynchronous storage
TimeDeadband
Minimum interval control:
- Prevents excessive writes
- Reduces storage requirements
- Maintains data integrity
Display Integration
TrendChart Control
Built-in visualization:
- Real-time trending
- Historical analysis
- Multiple pen support
- Zoom and pan features
Historian Monitor
Runtime monitoring interface:
- Table status display
- Error tracking
- Performance metrics
- Remote web access
Performance Optimization
Table Design
- Group by update frequency
- Limit tags per table (50-100)
- Match process dynamics
- Consider query patterns
Storage Strategy
- Choose appropriate schema
- Set retention policies
- Enable compression
- Plan capacity
Deadband Configuration
- Value deadbands for noise
- Time deadbands for frequency
- Deviation for exceptions
- Rate of change for upsets
Common Configurations
High-Speed Data
Storage: Local SQLite
Schema: Normalized
Trigger: SaveOnChange
TimeDeadband: 1 second
Retention: 30 daysProduction Records
Storage: SQL Server
Schema: Standard
Trigger: Batch events
SaveQuality: True
Retention: 365 daysCompliance Data
Storage: CanaryLabs
Store&Forward: True
SaveQuality: True
Retention: 7 years
Audit: EnabledAdvanced Topics
For deep technical understanding: → See [Historian Engine (Reference)]
Best Practices Checklist
Design
- Plan storage architecture - Match technology to requirements
- Group tags logically - Similar rates and relationships
- Size tables appropriately - Balance performance
- Configure deadbands - Optimize storage
- Set retention policies - Manage growth
Operations
- Monitor regularly - Check error counts
- Test failover - Verify Store and Forward
- Archive old data - Maintain performance
- Document configuration - Track changes
- Backup settings - Protect configuration
Performance
- Optimize queries - Use appropriate time ranges
- Index databases - Improve retrieval
- Cache frequently - Reduce database load
- Batch operations - Minimize transactions
Troubleshooting
Data Not Storing
- Verify trigger configuration
- Check table assignment
- Confirm database connection
- Review error messages
Incomplete Data
- Check module started status
- Verify tag quality
- Review deadband settings
- Examine triggers
Slow Retrieval
- Enable caching
- Optimize query ranges
- Check database indexes
- Review network latency
Store and Forward Issues
- Verify feature enabled
- Check local disk space
- Monitor buffer size
- Review sync status
In this section...
| Page Tree | ||||
|---|---|---|---|---|
|
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.
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 from a HistorianTable was generated (by the Trigger or OnTagChange events).
Archiving the data as needed.
Synchronizing with remote archives if store and forward or redundancy is enabled.
Replying to requests from displays and scripts on querying the archived data.
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 Namespace (Reference).
Historian Namespace
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.
Historian Engine 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 Historian Engine (Reference).
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.
In this section:
| Page Tree | ||||
|---|---|---|---|---|
|