RTV HTTP Rest Data Source
The RTView HTTP REST Data Adapter is an extensible data adapter that allows RTView to interact with REST APIs by means of HTTP requests. This data adapter provides an extensible framework with RTView, which uses the Apache HTTP Client to make HTTP requests. You can specify handlers to assist in the processing of an HTTP request.
The RTVHttpRest adapter supports data attachments that will execute an HTTP Request to get an HTTP Response, which can then be processed to extract a data table for use within RTView. The data attachments specify the handlers used for the various parts of making and processing an HTTP Request and Response. The data attachments allow the user to specify values that will be passed to handlers that implement the appropriate interfaces.
Default handlers are available, or you can implement custom handlers to extend functionality. There are examples of custom handlers in the custom/rtvhttprest directory of the RTView installation. See the README file in the custom/rtvhttprest directory for more information.
Note: The RTV HTTP Rest data source may not be licensed in your RTView installation.
This section includes:
| • | System Requirements and Setup - RTV HTTP REST |
| • | Attach to RTVHttpRest Data |
| • | Application Options - RTV HTTP REST |
| • | RTView Deployment - RtvHttpRest |
| • | Command Line Options - RtvHttpRest |
System Requirements and Setup - RTV HTTP REST
System Requirements
The RTV HTTP REST data source has no additional System Requirements.
Setup
The RTV HTTP REST data source requires no additional Setup.
Attach to RTVHttpRest Data
The Attach to RTVHttpRest Data dialog, which is used to define the HTTP request and the handlers used to process the request, can be accessed from the Object Properties window. The valueTable property of an object, typically a Cache object, will be attached to a data table received from the request. See Caches for more information.
Right-click on the Property Name from the Object Properties window and select Attach to Data> RTVHttpRest to display the Attach to RTVHttpRest Data dialog. The Attach to RTVHttpRest Data dialog provides several drop down menus that allow you to specify parameters of the request including the Client Handler, the Request Handler, and the Response Handler drop down menus, which list the names of the available handlers (default and custom).
|
Field Name |
Description |
|||
|
Client Handler |
The ClientHandler creates a client (CloseableHttpClient) that is used to execute a request (returned by the Request Handler) to return a response (processed by the ResponseHandler). A default client handler (com.sl.gmsjhttprestds.DefaultClientHandler) is provided, but you can create custom client handlers if needed. There are examples of custom handlers in the custom/rtvhttprest directory. See the README file in the custom/rtvhttprest directory for more information. |
|||
|
Headers |
Define additional headers to be used by the ClientHandler to populate the HTTP headers in the generated request. This field allows you to add additional headers to your request rather than having to modify the original request. Headers are set on ClientHandlers that implement the Headers interface. See the custom/rtvhttprest directory for examples. |
|||
|
Request Handler |
The RequestHandler creates a request (HttpUriRequest) that is executed by a client handler to return a response (processed by the ResponseHandler). A default request handler (com.sl.gmsjhttprestds.DefaultGetRequestHandler) is provided, but you can create custom request handlers if needed. See the README file in the custom/rtvhttprest directory for more information. |
|||
|
Request |
Enter the request that you want the RequestHandler to execute. The Request Handler may use the request as is or process it to extract additional information used in the request. The format of a URI used by an HTTP request is (where scheme is usually HTTP or HTTPS): scheme:[//[user:password@]host[:port]][/]path[?query][#fragment] |
|||
|
Content |
Specify any additional content that you want the RequestHandler to include in the body/payload of the HTTP request. This field allows you to add additional content to the payload instead of having to modify the original request. Content is set on RequestHandlers that implement the Content interface. See the custom/rtvhttprest directory for examples. |
|||
|
Response Handler |
The ResponseHandler returns the data (extracted by the RequestHandler) from the response. A default response handler (com.sl.gmsjhttprestds.DefaultResponseHandler) is provided, but you can create a custom response handler if necessary. See the README file in the custom/rtvhttprest directory for more information. |
|||
|
Mapping |
Specify additional mapping information that the ResponseHandler can use in the generated response. Mapping is set on ResponseHandlers that implement the Mapping interface. See the custom/rtvhttprest directory for examples. |
|||
|
Column(s) |
Name of the column 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. |
|||
|
Update Mode |
Select the desired polling interval from this drop down list. You can select from: Poll Every Default Poll Interval: refreshes data when the default polling interval occurs. Every Poll Interval: refreshes data when the value you defined in the Poll Interval field occurs. Poll On Demand: refreshes data when manually requested. Poll Once (Static Data): populates data only once and never refreshes the data. |
|||
|
Poll Interval |
Define the desired polling interval in which the data will be refreshed (if using the Every Poll Interval option). |
|||
|
Data Server |
Select to read data through your configured Data Server and not directly from the RTV HTTP REST 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.
|
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 RTVHttpRest 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 RtvHttpRest 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 RtvHttpRest 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 RtvHttpRest 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 REST
Select Tools>Options in the Display Builder to display the Application Options dialog, Then select RTVHttpRest from the left menu. Options specified in the RTVHttpRest tab can be saved in an initialization file (RTVHTTPRESTOPTIONS.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 RTVHTTPRESTOPTIONS.ini is not found in the directory where you started the application, then RTView will search under lib in your installation directory. See RTV_JAVAOPTS for more information.
Note: Options specified using command line arguments will override values set in initialization files. See Command Line Options - RtvHttpRest for more information.
*If you are enabling RTVHttpRest options to utilize the Historian for Alert Persistence, then you must copy the RTVHTTPRESTOPTIONS.ini file to the directory where you will be running the Historian.
RTVHttpRest Options Tab
This tab allows you to specify the polling interval that is used to refresh the data in the display.
|
Field Name |
Description |
|
Poll Interval (seconds) |
Define the polling interval (in seconds) used to refresh data in the display. By default, this option is set to 0. Once set, all objects with Update Mode (on the Attach to RTVHttpRest Data window) set to Poll Every Default Poll Interval will use this setting to refresh their data. |
RTView Deployment - RtvHttpRest
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.
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 REST, and RTV_JAVAOPTS for more information.
Include the following initialization file when you deploy RTView with this data source:
|
File Name |
Description |
|
RTVHTTPRESTOPTIONS.ini |
Contains general options as well as data source options for RtvHttpRest. |
Note: Options specified using command line parameters override values set in these initialization files.
Command Line Options - RtvHttpRest
In addition to General Options, the following command line arguments are enabled with the RtvHttpRest 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 |
|
-rtvhttpresttrace: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: -rtvhttpresttrace:6 |