RTV HTTP Data Source

Note: The RTV HTTP data source may not be licensed in your RTView installation.

The RTView HTTP Data Adapter is an extensible data adapter that allows you to process data (that has been posted to a particular URL) using a defined handler. You enable and specify the root and handler URL via Application Options - RTV HTTP, and then process the data using the handler defined in Attach to RTVHttp Data.

You can use the default handlers, which can be added by copying the RTVHTTPOPTIONS.ini file (in the custom/rtvhttp directory) to your working directory or to the lib directory (which is located in your installation directory). See the README file in the custom/rtvhttp directory for more information on using the handlers provided with the RTView HTTP Data Adapter.

This section includes:

• System Requirements and Setup - RTV HTTP
• Attach to RTVHttp Data
• Application Options - RTV HTTP
• RTView Deployment - RTV HTTP
• Command Line Options - RTV HTTP

 

System Requirements and Setup - RTV HTTP

System Requirements

The RTV HTTP data source has no additional System Requirements.

Setup

In order to use the pre-defined default handlers, perform the following steps:

1. Go to the custom/rtvhttp directory and copy the RTVHTTPOPTIONS.ini to your working directory (or to the lib directory (which is located in your installation directory) so that it will work from any directory in which you are working).
2. To verify that the defaults are displaying properly, run the display builder and select Tools > Options.

The Application Options window displays.

3. Select RTVHttp from the left menu.

The RTVHttp Handlers tab displays by default with the DEFAULT_CACHE_WRITER and DEFAULT_JSON_HANDLER options listed in the Handlers list box. DEFAULT_JSON_HANDLER is listed as the Default Handler. See Application Options - RTV HTTP for more information.

See the README file in the custom/rtvhttp directory for more information. See Setup for the basic setup required.

Attach to RTVHttp Data

Right-click on the Property Name from the Object Properties window and select Attach to Data> RTVHttp to display the Attach to RTVHttp Data dialog. The Attach to RTVHttp Data dialog provides several drop down menus including the Handler Name, which is the name of the handler you want to use to process the data, and the Table Name, which is the table from which you want to collect data.

 

 

Field Name

Description

Handler Name

Select the handler that you want to use to process the data posted on the pre-defined URL (which was set up in Application Options - RTV HTTP). The pre-defined default handlers and any custom handlers you have created display in this drop down list.

Table Name

Select the table name from which you want the handler to collect data.

Column(s)

Name of the column within the table to use as a filter. Multiple column names should be entered as a semicolon (;) delimited list (i.e. col1;col2;col3). If your column name contains a space or a semicolon, then the entire name must be enclosed in single quotes.

Filter Rows

Select this check box to enable the Filter Column and Filter Value fields.

Filter Column

The name(s) of the column(s) to which the Filter Value should be applied.

Filter Value

The filter value(s) to be applied to the filter column(s). Multiple filter values should be entered as a nested list, where values for a given column are separated by commas within a semicolon (;) delimited list (i.e. val1,val2;val3,val4;val5,val6). If your filter value contains a space or a semicolon, then the entire value must be enclosed in single quotes.

When * is entered as a filter field value, data for all values in the specified filter column will be used to update the object property. When "*" is entered, only the literal comparative value will be used.

Data Server

Select to read data through your configured Data Server and not directly from the RTV HTTP data source.

Default - Select the default Data Server you configured in Application Options>Data Server Tab

None - Bypass data being redirected through the specified data server(s) for this attachment and instead attach directly to the data source.

Named Data Servers - Select a Named Data Server that you configured in Application Options>Data Server Tab.

Multi-Server Attachment - To configure multiple data servers, enter a semicolon (;) delimited list containing two or more Named Data Servers (e.g. ds101;ds102). Each name specified must correspond with a Named Data Server that you configured in Application Options>Data Server Tab. It is also possible to specify __default and __none (e.g. __default;ds101;ds102).

Note: The values __default and __none begin with two underscore characters.

 

Alternatively, a value of * can be entered to specify all data servers, including __default and __none.

When multiple data servers are specified, the data attachment will be directed to each data server in the list. For tabular data attachments, a column named DataServerName will be added as the first column of the table and contain the name of the server from which the data was received.

 

A multi-server attachment will receive data independently from each of the servers it specifies, so in most cases it will be necessary to combine the tables received into a single table. This can be accomplished in two ways:

The multi-server attachment can be applied to a local cache that has the DataServerName column specified as an index column. The current table of that cache will contain the combination of the tables received from all servers. Note: It may also be necessary to configure cache row expiration settings to remove defunct rows.

4. The multi-server attachment can be applied as the Table argument of the RTView function named Combine Multi-Server Tables. See Tabular Functions for more information.

When an object property is attached to data, the Property Name and Value in the Object Properties window will be displayed in green. This indicates that editing this value from the Object Properties window is no longer possible. Once a property has been attached to data, it receives continuous updates. To remove the data attachment and resume editing capability in the Object Properties window, right-click on the Property Name and select Detach from Data. You will recognize that an object property has been detached from the data source when the Property Name and Value are no longer green.

Validation Colors

Fields in the dialog change colors according to the information entered. These colors indicate whether or not information is valid. Information entered into the dialog is validated against the data received.

The following describes the significance of the Attach to RTVHttp Data validation colors:

 

Blue

Unknown

Cannot validate entry.

White

Valid state

Entry is valid.

Red

Invalid state

Incomplete or invalid entry.

*If the entry is validated as Unknown, RTView will attempt to read it when you click OK or Apply.

Substitutions

The Substitutions feature allows you to build open-ended displays in which data attachments depend on values defined at the time the display is run. A generic name such as $table is used instead of a specific table name. Later, when the display is running, this generic value is defined by the actual name of a specific table, such as SalesTable. In this way, a single display can be reused to show data from a number of different sources. For more information on creating displays using substitution values, see Substitutions.

Select Table Columns

You can specify which table columns to display and in what order they will appear from the Attach to RtvHttp Data dialog. Since the incoming data can constantly change, the Available Columns region on the Available Columns window will not be populated automatically. You either need to know the column names in the incoming data or you need to view the incoming data beforehand to determine the column names.

Once you know the column names in the incoming data, there are two ways to specify the columns that you want to view. You can either enter the column names directly in the Column(s) field (using a semi-colon to separate the column names when specifying multiple columns), or you can click on the ellipses button in the Column(s) field (or right-click in the Column(s) field and choose Select Columns) to display the Select Columns dialog. To add a column, type the name of the column you want to add in the Enter Column Name field and click the Add button. Click the Remove button to delete an item previously added to the Selected Columns list. You can control the order of columns in a table by arranging the items in the Selected Columns list with the Move Up and Move Down buttons.

Validation colors indicate whether selected columns are valid. However, if even one column selected is invalid, the Column(s) field in the Attach to RtvHttp Data dialog will register as an invalid entry.

Note: Invalid columns will not update.

If no data is available for a table row within a selected column, the table cell will be empty or will display one the following values: N/A, false, 0, or 0.0.

 

The following describes the Attach to RtvHttp Data dialog commands:

 

Command

Description

OK

Applies values and closes the dialog.

Apply

Applies values without closing the dialog.

Reset

Resets all fields to last values applied.

Clear

Clears all fields. Detaches object from data source (once Apply or OK is selected).

Cancel

Closes the dialog with last values applied.

Application Options - RTV HTTP

Select Tools > Options in the Display Builder to display the Application Options dialog, and then select RTVHttp in the left menu. There are two tabs available:

• RTVHttp Handlers Tab: This tab allows you to select, create, update, and remove handlers.
• RTVHttp Options Tab: This tab allows you to enable the RTV HTTP Data Source, to specify the default port to use, to specify the root URL, and to require HTTPS to be used.

Options specified in the RTVHttp tab can be saved in an initialization file (RTVHTTPOPTIONS.ini). On startup, the initialization file is read by the Display Builder, Display Viewer, Display Server, Data Server, and Historian* to set initial values. If no directory has been specified for your initialization files and RTVHTTPOPTIONS.ini is not found in the directory where you started the application, then RTView will search under lib in your installation directory.

Note: Options specified using command line arguments will override values set in initialization files. See Command Line Options - RTV HTTP for more information.

*If you are enabling RTVHttp options to utilize the Historian for Alert Persistence, then you must copy the RTVHTTPOPTIONS.ini file to the directory where you will be running the Historian.

RTVHttp Handlers Tab

This tab allows you to select a default handler, add a new handler, edit an existing handler, and remove an existing handler.

 

 

Field Name

Description

Default Handler

Select the handler that you want to use as the default. The handler selected from this drop down will be the default handler that displays in the Attach to RTVHttp Data window.

Note: This drop down list will default to the handler specified in the rtvhttpdefaultconn __name property in the RTVHTTPOPTIONS.ini file.

Add Handler

Clicking the Add Handler button displays the Add RTVHttp Handler window, which allows you to add a handler. Once added, the new handler displays in the Handlers display list. This window contains the following fields and buttons:

 

Handler Name: Specify the name for the new handler.

Java Class: Specify the Java class for the new handler.

Handler URL: Specify the URL for the new handler. This URL is appended to the Root URL defined in the RTVHttp Options Tab tab to define the complete URL from which the data is collected. For example, if the Root URL is defined as /rtview and this URL is defined as /json/data, then the entire URL would be defined as /rtview/json/data.

OK: Saves any changes made to the window.

Reset: Returns all fields to their original settings (when the window was first opened).

Clear: Clears any text in the fields.

Cancel: Closes the window without saving any changes made.

Help: Displays a pop-up window with definitions for the fields on the window.

Remove Handler

Selecting a handler from the Handlers display list and then clicking this button removes the handler from the display list.

Handlers

Lists the default handlers and any custom handlers that have been created. Double-clicking on one of the handlers in this display box opens the Add RTVHttp Handler window with the currently defined properties for the selected handler.

RTVHttp Options Tab

This tab allows you to enable the RTV HTTP Data Source, specify the port to be used, specify the root URL, and specify whether or not to require HTTPS to be used.

 

 

Field Name

Description

Enabled

Selecting this check box enables the RTV HTTP Data Source functionality and displays the Port field, the Root URL field, and the Use Https check box.

Port

Specify the port to which you want to connect to collect data.

Root URL

Specify the URL to be used as the root portion of the URL. The Handler URL, as defined on the RTVHttp Handlers Tab, will be appended to this URL to form the complete URL.

Use Https

Selecting this check box requires that HTTPS be used for the defined URL.

RTView Deployment - RTV HTTP

This section contains details about the deployment process that are specific to your data source. Please go to the Deployment section of this documentation for instructions on how to implement your RTView deployment option. Return to this page whenever you are instructed to refer to deployment information that is specific to your data source.

Note: If the application(s) posting data to the HTTP Data Source cannot post directly to your RTView Application due to security or post access limitations, then complete the section titled Set up RTVPost Servlet on Application Server. Your application(s) can then post data to the RTVPost Servlet, which will forward the data to RTView. See RTView Core® User’s Guide Version 7.4 for more information on application deployment, or RTView Core® User’s Guide Version 7.4 for more information on browser deployment.

This section includes:

• System Requirements and Setup
• Data Source Configuration File

System Requirements and Setup

There are no additional setup steps required for this data source.

Data Source Configuration File

RTView saves general application settings as well as data source configuration options in initialization files that are read at startup. If no directory has been specified for your initialization files and files are not found in the directory where you started the application, then RTView will search under lib in your installation directory. See Application Options, Application Options - RTV HTTP, and RTV_JAVAOPTS for more information.

Include the following initialization file when you deploy RTView with this data source:

 

File Name

Description

RTVHTTPOPTIONS.ini

Contains defined handler names and the options specified in the RTVHttp Options Tab for the RtvHttp data source.

Note: Options specified using command line parameters override values set in these initialization files.

Command Line Options - RTV HTTP

In addition to General Options, the following command line arguments are enabled with the RtvHttp data source when you run RTView applications from a Windows Command Prompt or UNIX terminal window. See Command Line Options: Display Builder and Display Viewer for more information.

Note: If a command line argument contains a space or a semicolon, then the entire argument must be enclosed in quotes (e.g.: "-sub:$data:my Data").

 

Name

Description

-rtvhttptrace:N

Enable data source specific tracing. N is an Integer and higher numbers yield more trace output. Default for this option is no tracing enabled (-rtvhttpresttrace:0).

Example:

-rtvhttptrace:6