rtview-utils

rtview-utils - RTView Utility Package for JavaScript

The rtview-utils package contains JavaScript utility functions that can be used in a Node.js application to transmit custom monitoring or IoT data to an RTView DataServer.

RTView is a real-time data management, visualization and analytics engine provided by SL Corporation (www.sl.com). It is used by organizations worldwide as a key component of mission-critical monitoring and control systems built around various middleware, infrastructure and IoT data sources.

The RTView DataServer is the data management component that provides in-memory caching and archival to persistent storage. Data stored there may be consumed by displays, dashboards, reports and alerts provided by a visualization and analytics tool such as RTView Cloud.

The RTView DataServer provides a REST API for defining data structures and transmitting data to be stored in its caches. The 'rtview-utils' package provides a set of functions that shield the user from this REST syntax and make it easier to perform these operations from a JavaScript program.

The JavaScript API in this package enables users to:

• define RTView data cache(s), i.e. names and types of index, history, and data columns
• transmit data records to RTView with the proper structure
• optionally batch data records for performance optimization
• retry transmission after a lost connection

Installation

The rtview-utils package is a Node module which can be installed using npm:

npm install rtview-utils

Alternatively, the package.json file could be edited to include the lines below, and a simple call to 'npm install' will suffice.

"dependencies": {
    "rtview-utils": ""
}

Usage

To use the RTView utility functions in a JavaScript application, an instance of the rtview-utils package is 'required'. Near the top of your program file, add the following line of code to make an instance:

var rtview = require('rtview-utils')();

The utility functions contained within the package are scoped to this 'rtview' instance, and may be invoked as shown in this simple example below.

// Send one row of data to a cache named SensorData

var sensorCacheName = "SensorData";
var sensorData = {
    "ID" : "Sensor_01",
    "temperature" : "24.57",
    "humidity" : "44.11"
};
rtview.send_datatable (sensorCacheName , sensorData);

Typically, the RTView DataServer is started first. It can be invoked either as a simple Java application on a local machine or as a service in a Virtual Machine or Docker Container running on a cloud platform. The www.sl.com website provides information about downloading and running the RTView DataServer.

Once the DataServer becomes available, the application would create the required cache data structures, using a series of calls to the create_datacache() function. This would be followed by repeated calls to the send_datatable() function to transmit real-time data records to the DataServer to be stored in its caches and optionally archived to persistent storage.

Detailed descriptions of these functions, along with useful examples, are provided in the API section below.

API

Table of Contents

• rtview-utils
  • Examples
• set_targeturl
  • Parameters
  • Examples
• set_batchsize
  • Parameters
  • Examples
• set_interval
  • Parameters
  • Examples
• create_datacache
  • Parameters
  • Examples
• send_datatable
  • Parameters
  • Examples
• flush_buffer
  • Parameters
  • Examples

rtview-utils

RTView Utility Package for JavaScript

A set of Utility functions for communication of real-time structured data to an RTView DataServer.

Examples

// Configure the application to make use of the rtview-utils package
// and reference it using the variable name 'rtview'
 
var rtview = require('rtview-utils')();

set_targeturl

Set Target URL of RTView DataServer.

The target URL is a string which is composed of either:

1. the hostname of the computer hosting the DataServer concatenated with its HTTP port or
2. the address of the application server to which an rtvpost proxy servlet has been deployed.

If this function is not called, the default value for 'url' is 'http://localhost:3275'.

In the case of direct HTTP port access, the specified port must be accessible. When using the rtvpost servlet, the application server’s URL must be accessible.

Parameters

• url string http(s) URL of RTView DataServer

Examples

// Configure package to send data to an RTView DataServer running on 'myhost'
// and exposing an http servlet named 'rtvpost'
 
var myURL = 'http://myhost/rtvpost';
rtview.set_targeturl (myURL);

set_batchsize

Set Batch Size for data transmission.

This function configures the application to buffer data sent to the RTView DataServer using the send_datatable() function. When the number of rows reaches the specified batch size, then all the accumulated data are sent in one batch. This technique reduces the number of http posts to the DataServer. If this function is not called, the default value for 'size' is 50.

Parameters

• size number number of data rows per batch

Examples

// Send data when number of buffered rows reaches 100
 
var myBatchSize = 100;
rtview.set_batchsize (myBatchSize);

set_interval

Set Timer Interval.

This is the maximum time before data rows that have been buffered are actually sent to the RTView DataServer. If this function is not called, the default value for 'interval' is 2000, and rows are sent at least once every 2 seconds.

Parameters

• interval number maximum interval (in milliseconds) between transmissions

Examples

// Send data at an interval of ten seconds
 
var myTimerInterval = 10000;
rtview.set_interval (myTimerInterval);

create_datacache

Create a named data cache in the targeted RTView DataServer with the specified properties and structure.

Call this function once for each named data cache required by the application. The DataServer must be active and accepting requests in order for the cache to be created. Once created, its structure is persisted until this function is called again and it is redefined. Multiple caches may be defined within each DataServer.

See the 'Additional Information' section below for details about cache properties and data types that are supported.

Parameters

• cacheName string name of the cache to create
• properties Object set of name:value pairs defining cache properties
• metadata Array<Object> array of name:value pairs defining type of each data element

Examples

// Create a cache named SensorData with the specified properties and structure
 
var sensorCacheName  = "SensorData";
var sensorProperties = {
    "indexColumnNames" : "ID",
    "historyColumnNames" : "temperature;humidity"
};
var sensorMetadata = [ 
    { "ID" : "string" },
    { "temperature" : "double" },
    { "humidity" : "double" }
];
rtview.create_datacache(sensorCacheName, sensorProperties, sensorMetadata);

send_datatable

Send a set of data rows to the specified RTView cache.

The 'data' argument may be a single data row, i.e. an array of name/value data elements. Multiple rows may be sent in a single call by passing an array of such data rows. The structure of a data row must match exactly the structure of the 'metadata' argument to the create_datacache function that defined the cache.

Rows sent using this function are buffered until either the batch size has been reached or the timer interval has completed.

Parameters

• cacheName string name of the cache to transmit
• data Array<Object> one row or an array of rows of properly formatted data objects (name:value pairs)

Examples

// Send one row of data to a cache named SensorData
 
var sensorCacheName = "SensorData";
var sensorData = {
    "ID" : "Sensor_01",
    "temperature" : "24.57",
    "humidity" : "44.11"
};
rtview.send_datatable (sensorCacheName , sensorData);

flush_buffer

Flush the buffer associated with a specific cache.

Send all rows buffered so far, even if time interval has not completed.

Parameters

• cacheName string name of the cache to flush

Examples

// Flush buffer associated with theSensorData cache
 
var sensorCacheName = "SensorData";
rtview.flush_buffer (sensorCacheName);

Additional Information

The RTView data cache properties and the available data types are described in this section.

Available Data Types

The metadata argument to the create_datacache() function is used to specify the exact column structure for the cached data. It is an ordered array of name value pairs, where the name is the name of the column and the value is its data type. The following types are recognized by the RTView DataServer:

"string"    - string
"boolean"   - 'true' or 'false'
"integer"   - integer
"float"     - floating point number
"double"    - double-precision floating point number
"date"      - standard 'date' type, an integer representing number of milliseconds since 1970

Cache Properties

An RTView data cache is a data structure maintained by the RTView DataServer. It provides a real-time multi-dimensional current value table consisting of multiple rows and a specified column structure. It is indexed by one or more of the data columns. Additionally, in-memory history may be optionally maintained as a secondary table that records all changes to uniquely indexed data rows. A subset of data columns may be specified for inclusion into the history table.

It is not required to provide a time_stamp column in the cache metadata or in the datatable transmitted to the DataServer. A time_stamp column is always added to the cache as its first column if a column by that name is not provided in the data, and its value set to the time at which the data record was received by the DataServer.

The following properties are available to specify important characteristics of each cache defined by the create_datacache() function. Multiple values may be separated by semi-colons in the property value:

"indexColumnNames"              - one or more columns that uniquely index data rows 
                                    (default = "" = none)
			  
"historyColumnNames"            - one or more columns that will be stored to history table
                                    (note that the time_stamp and all index columns are always stored in history)
                                    (default = "" = all)
			  
"maxNumberOfHistoryRows"        - maximum number of rows that can be stored in history table
                                    (default = 500000, set to 0 for no history) 
			  
"maxNumberOfCurrentRows"        - maximum number of uniquely indexed rows that can be stored in current table
                                    (default = 10000, set to 0 for unlimited)
			  
"historyTimeSpan"               - maximum time span in seconds before data rows are purged from history table
                                    (default = 15d (15 days), set to 0 for unlimited)

The RTView data cache also manages data expiry. If a row of data for a particular index has not been received within the specified 'expiration time', an additional column named 'Expired' is marked as 'true'. If no data are received within the 'expiration time for delete', then the row is deleted from the cache completely. These times can be configured with the properties below:

"rowExpirationTime"             - number of seconds before row is marked as 'Expired'
                                    (default = 30)
                  
"rowExpirationTimeForDelete"    - number of seconds before row is removed from cache
                                    (default = 3600, or one hour)

Complete Example

The following is a complete example that creates a simple cache and sends one row of data to it.

// Configure the application to make use of the rtview-utils package
// and reference it using the variable name 'rtview'

var rtview = require('rtview-utils')();

// Configure package to send data to an RTView DataServer running on 'localhost:3270'
// and exposing an http servlet named 'rtvpost' (the default out-of-the-box dataserver)

var url = 'http://localhost:3270/rtvpost';
rtview.set_targeturl(url);

// Create a cache named SensorData with the specified properties and structure

var sensorCacheName  = "SensorData";
var sensorProperties = {
    "indexColumnNames" : "ID",
    "historyColumnNames" : "temperature;humidity"
};
var sensorMetadata = [ 
    { "ID" : "string" },
    { "temperature" : "double" },
    { "humidity" : "double" },
    { "temp_unit" : "string"}    // a column that is neither index nor history
];
rtview.create_datacache(sensorCacheName, sensorProperties, sensorMetadata);

// Send one row of data to the SensorData cache

var sensorData = {
    "ID" : "Sensor_01",
    "temperature" : "24.57",
    "humidity" : "44.11",
    "temp_unit" : "°C"
};
rtview.send_datatable(sensorCacheName , sensorData);

back to top