Configuring the Historian

This section describes how to configure the Historian. For information about the Advanced Historian, see the “Advanced Historian” section.

The Historian is used to archive data from any RTView data source to any database using JDBC. The SQL data source is required to view data from the Historian in RTView. It is not required to use the Historian to archive data. You can verify that the SQL data source is licensed in your installation in the Display Builder About dialog. See “RTView Data Sources” for more information.

You configure the Historian by creating Data Configuration (.rtv) files, configuring the Historian to create connections to your data sources, and setting final configurations in the Historian application. The Data Configuration (.rtv) files specify which data the Historian is to archive from each data source. You create Data Configuration (.rtv) files in the Display Builder. The Data Configuration (.rtv) files also specify how to access the data, and perform required transformations in the data.

When you start the Historian, it immediately begins gathering data as specified and places the time-stamped data into the designated tables. After the Historian has stored data over a period of time, you can build a display using History data. See “Building a Display Using History Data” for more information.

You can install multiple versions of the Historian to segment data collection into different databases, and configure fault-tolerance. The Historian comes with default schemas that are largely configurable. For example, you can use configuration files to specify your own table names and, optionally, let the Historian automatically create the tables in your database if they do not already exist. See “Configuring Failover on the Historian” for more information.

Data Configuration File Options

To configure the Historian you create Data Configuration (.rtv) files in the Display Builder. Data Configuration (.rtv) files specify which data to archive from each data source, how to access the data, any transformations to perform with the data, and the table in which to then store the data. There are two Data Configuration (.rtv) file options, Display Files or Cache Definition Files.

Display Files

Use this option if your RTView deployment does not use caches. With this option you use your existing RTView display (.rtv) files (that you created in the Display Builder) to configure the Historian. Your existing display (.rtv) files contain objects that are already attached to your data. A record is stored in the history database every time new data is received by the Historian for each data attachment in your configuration display.

To use RTView display (.rtv) files to configure the Historian, you must have two history tables configured in your database: one for numeric data, the other for string data (for example, textual data). Numeric values must be attached to numeric object properties, and text values must be attached to string object properties. If you attach a numeric value to a meter label (which is a string object property), the numeric value is stored in the database as a string instead of a number, and the data is not available for trend graphs.

Cache Definition Files

Use this option if your RTView deployment uses caches or, if you need to use the “Advanced Historian”. With this option you configure Cache object properties to point to the historical data to be archived. You can also specify which sources of current and/or historical data to keep in memory. To configure the Historian using this option, you specify which of these cached values to archive in a history database and then use these cache definition (.rtv) files to configure the Historian. The cache definition (.rtv) file specifies the following for the Historian: the data source, the cache and the database in which to store historical data.

The Cache data source allows for much higher performance than the traditional means of either performing analytics on information stored in a database, or querying it from the database to make calculations.

This section contains the following:

§        “Basic Steps To Configure the Historian” on page 1139

§        “Display File Configuration” on page 1140

§        “Cache Definition File Configuration” on page 1143

§        “Database Connection Configuration” on page 1145

§        “Historian Application Configuration” on page 1145

§        “Configuring Failover on the Historian” on page 1149

Basic Steps To Configure the Historian

Perform the following steps in the order given to configure the Historian:

1.     Create or prepare Data Configuration files using the RTView Builder. Choose one:

•        “Display File Configuration”

•        “Cache Definition File Configuration”

For help choosing the type of Data Configuration file, see Data Configuration File Options.

2.     Configure Database Connections (see “Database Connection Configuration”). You can configure the Historian to create connections to your data sources using a direct JDBC connection.

3.     Configure the Historian application database connection. See “Historian Application Configuration” for more information.

4.     After the Historian has stored data over a period of time, you can build a display using History data. See “Building a Display Using History Data” for more information.

Display File Configuration

Perform the following steps to create a Data Configuration (.rtv) Display File for configuring the Historian. These procedures assume you are using your existing RTView display (.rtv) files (the displays you currently use to view your data) to configure the Historian. These procedures assume that you have already attached your historical data to an object.

To configure the Historian using a Display File:

1.     In the Display Builder, verify that your data is attached to the appropriate type of object property for the corresponding value. That is, numeric values must be attached to numeric object properties, and text values must be attached to string object properties. If you attach a numeric value to a meter label (which is a string object property), the numeric value is stored in the database as a string instead of a number, and the data will not be available for trend graphs).

2.     Verify that you have two history tables in your database: one for numeric data, and another for string data (textual data). If you do not, configure the two tables. By default, if the -rebuildtables option is on, the first time you run the Historian two tables are created: a numeric table named HISTORY and a string table named HISTORY_S. See “Command Line Options: Historian” for more information.

If you can verify the default numeric table (HISTORY) and the string table (HISTORY_S) are in your database, and you want to use these tables, proceed to “Database Connection Configuration”.

If you do not want the Historian to create the HISTORY and HISTORY_S tables, you can create your own history tables manually. The tables must be created before running the Historian application.

To create your own history tables, use your preferred database client tools or database vendor client tools to do the following:

A. Use the -tablename command line option for the Historian to specify a single table name (other than HISTORY and HISTORY_S). The table name you specify is used for the numeric table, and _S is appended to the name to create the string table. See “Command Line Options: Historian” for more information. For example, if you specify:

MY_TABLE 

The table name MY_TABLE is then established, and another table name is automatically created which has _S appended to the name. You then have the following two tables:

MY_TABLE is used for the numeric table.

MY_TABLE_S is used for the string table.

Note: Table names cannot contain spaces.

B. Configure the numeric table as described in the “Numeric Data Table”, below.   

C. Configure the string table as described in the “String Data Table”, below.   

D. Specify the table name on the command line for the Display Builder and Display Viewer Application and/or in your Display Viewer Applet parameters. See “Command Line Options: Display Builder and Display Viewer” and “Rich Client Browser Deployment” for more information.

Note: The two manually created tables are automatically rebuilt as data is received (you do not need to manually rebuild the tables).

Note: Tables created manually cannot utilize the valueHistoryFlag property to load initial history data on graph traces. See “Enable valueHistoryFlag” for more information.

Numeric Data Table

The following fields are supplied in the numeric data table (HISTORY or the table name you specified):

Note: If you select the historyTableRowNameFlag check box in Object Properties, then you must include and additional text column placed at the beginning of the table to store row name values. The Historian assumes that columns in the history table you create are in the same order as those in your tabular data element. If not, you can use the -insertColumnNames command line option for the Historian to match data to the correct columns. See “Command Line Options: Historian” for more information.

String Data Table

The following fields are supplied in the string (textual) data table (HISTORY_S or the table name you specified):

Note: When you attach data to a tabular object property, such as valueTable, it is recommended that you create a table in the history database to store that data. If you do not create a table, data from your tabular element is stored in standard history tables and, in the case of tabular data with multiple columns, row integrity is lost. See “Tabular Functions” for details about how to store tabular data.

For step-by-step instructions on creating data configuration files for the Historian or to learn how to create a table in the history database to store tabular data, go to Examples>Historian.

Proceed to “Database Connection Configuration”.

Cache Definition File Configuration

Perform the following steps to configure the Historian using a Cache Definition File. The Cache Definition file specifies the following for the Historian: the data source, the cache, and the database in which to store historical data. In these Steps you specify your data source and your cache. See “Cache Definition Files” for more information.

To configure the Historian using a Cache Definition File:

1.     Use the RTView Builder to create a Cache Definition file, or select a cache on which you want to enable the Historian.

2.     Select the cache from the Caches dialog and edit the following Historian properties in the Object Properties dialog. (In this Step you specify your cache.)

3.     When you have finished configuring the properties, Save the display (.rtv) file. You will add this Cache Definition file to the list of Data Configuration files in the Historian application. See “Data Configuration File Options” for more information.

Proceed to “Database Connection Configuration”, next.

Database Connection Configuration

Perform the following steps to configure the Historian connections to your data sources. There are two options: “Direct JDBC Connection” or “Historian Application Configuration”.

Direct JDBC Connection

For the Historian to use a direct JDBC Connection to communicate with your database,  you must have a JDBC driver for your database. JDBC drivers are available from most database vendors.

To configure a direct JDBC Connection:

1.     Locate the JDBC driver on your machine.

2.     Define an environment variable named RTV_USERPATH that includes a path to the driver class or .jar file containing the driver class.

Note: You can define RTV_USERPATH to include paths to multiple driver classes. The RTV_USERPATH variable is included in the classpath for RTView and the Historian.

3.     Note the fully qualified class name for the driver class and the database URL required to connect to your database. You need this to setup the database (when you configure the Historian application--see “Historian Application Configuration”). The database URL typically contains protocol and sub-protocol strings for your database, as well as the path to the database and a list of properties. If you do not know the syntax for your database URL, consult the documentation for your JDBC driver.

Proceed to “Historian Application Configuration”.

Historian Application Configuration

This section describes how to add the Data Configuration file you previously created to the Historian application, and configure the database in which your historical data will be stored. See “Data Configuration File Options” for more information.

The Historian Application allows you to configure the database connection. Click Save Configuration to save these settings. The Historian Console tab records errors and information. If you select the Show Data in Console check box, the Historian Application will output a line for each record that is stored in the database.

Data source-specific options are read in from initialization (.ini) files created in the Display Builder. For information on creating initialization files or command line options for your data source, refer to Applications Options or Command Line Options in the Data Sources section of this documentation.

To configure the Historian Application

1.     Start the Historian.

In an initialized terminal window (see “Initializing a Command Prompt or Terminal Window”) type: run_historian 

The Historian application opens and begins gathering and placing your (now time-stamped) data into tables based on your Data Configuration file specifications.

2.     Click Configuration to edit settings.

3.     Make the following Database Options entries as appropriate:

4.     Make the following Record Retention Options entries as appropriate:

5.     Make the following Data Cache Options entries as appropriate:

6.     Make the following Alert Persistence entries as appropriate:

Note: Alerts are sent from the application running the alert engine to the Historian via the RTVAgent. Therefore, you must enable connections from remote agent applications on the “RTVAgent Options Tab” and then copy the RTVAGENTOPTIONS.ini file to the directory where you will be running the Historian.

Note: The Historian must run the RTVAgent data source locally (not via a Data Server) to persist the alerts. If you are running the Historian against a Data Server you can run the RTVAgent data source locally using the following command line option: run_historian -dsenable:RTVAGENT

7.     In Data Configuration Files, click Add, enter the name of the Data Configuration (.rtv) file you just created and, optionally, any corresponding substitutions. “Substitutions” allow the same file to be used multiple times by different sets of substitutions.

Note: Each cache that is defined in the file should contain a substitution in the cacheName property, since cache names must be unique.

8.     Click Apply to execute. Data Configuration files are added or removed after you click OK, Apply, or Save.

Note: To edit the Data Configuration (.rtv) file and apply changes without restarting the Display Builder, select a file from the list and click Refresh Selection to reload definition settings. The Refresh Selection option is enabled when you select a Data Definition (.rtv) file that has been both added and applied.

The Data Configuration (.rtv) file is added to the data source and data for these caches is collected. See the “Attach to Cache Data” section for details about attaching to cache data variables.

Note: After a Data Configuration (.rtv) file has been added to the data source, data is collected for that cache regardless of whether any currently open display (.rtv) files are showing that data.

9.     Select Show Data in Console so that the Historian prints out a line for each record that is being stored in the database.

10.  Select Start Storing Data.

11.  Select Save Configuration.

12.  Verify your configuration by clicking Console to view the Show Data in Console output.

Your setup is complete. After the Historian has stored data for a period of time, proceed to “Building a Display Using History Data”.

Optionally, you can configure failover for the Historian. For information, see “Configuring Failover on the Historian”.

Configuring Failover on the Historian

This section describes how to configure failover for the Historian. You configure failover in the Historian application. For details about configuring the Historian, see “Configuring the Historian”.

High Availability Historians

The High Availability feature is intended to be used with a database system that also supports redundancy (through mirroring, clustering, or other techniques) so that any Historian in the group can update the same virtual database.

To configure failover, create a Server Group and designate backup Historians to support a failover event. By default, no Server Group is defined.   You can specify a primary Historian as well as one or more backup Historians. Only the primary Historian is capable of writing to the database.   

Each Server Group member is assigned a port number and a priority. Using a socket connection on the assigned ports, each member monitors the status of the others in the group. The member with the highest priority is elected as the primary Historian. If the primary Historian fails, is shut down, or loses its connection to the database, the backup Historian with the highest priority becomes the new primary. A Historian with a priority of 2 is has higher priority than a Historian with a priority of 1.

For example, if we have three Historians with the following priority:

Historian A / Priority 1

Historian B / Priority 2

Historian C / Priority 3

and Historian C is the Primary. If Historian C is shut down, Historian B becomes the Primary. In the event of a tie in priority ranking, the Historian that was started first becomes the primary.

Note: Each Historian in the group should be configured with the same set of data configuration files, retention options, data source options, etc.

To configure failover for the Historian:

1.     Start the Historian application.

In an initialized terminal window (see “Initializing a Command Prompt or Terminal Window”) type: run_historian

The Historian application opens.

2.     Click the Server Group tab and make the following entries:

3. Click Save Configuration.