Enterprise RTView® 
User Guide

Rich Client Browser with Direct Data Connection - Setup

This section provides step-by-step instructions on how to deploy Enterprise RTView. The steps must be done in the order given. Refer to Rich Client Browser with Direct Data Connection - Deployment Process for a summary of these instructions.

NOTE: This documentation is intended for users with a working knowledge of HTML code and application server administration. If you do not have a full understanding of these topics, you will need assistance from your system administrator.

An Apache Tomcat application server is included with your Enterprise RTView installation for prototyping and testing your deployment before going into the production environment. The following instructions will work for your application server or the one that comes with Enterprise RTView.

Step 1: Setup Applet on Application Server

A: Verify System Requirements
Verify the following system requirements:
  • Application server.
  • Basic system requirements
  • In addition to basic system requirements, refer to the Data Sources section of this documentation for system requirements and setup specific to your data source.

When finished return to Part B: Configure Applet.


B: Configure Applet
At this point you have verified your system requirements.

In this section, you will create an HTML page that instances the Display Viewer Applet. All of the jars necessary to run the Display Viewer Applet can be found under your installation directory located in the lib directory. The jars in the lib directory are not digitally signed. If you need to deploy with signed jars, use the jars in lib\signed-jars.zip. The certificate in these jars will expire in March of 2009. 

Create an HTML page that instances the Display Viewer Applet. This procedure has two Parts:
  • Part i: Specify Required Applet Parameters
  • Part ii: Specify Optional Applet Parameters
NOTE: The Display Viewer Applet also supports several JavaScript methods.

Display Viewer Applet Example
A sample HTML page, mydisplay.html, contains the Display Viewer Applet and can be found in your installation directory under demos. The minimum HTML code required to run the Display Viewer Applet are as follows:
<html>
<body>
<object classid="clsid:8AD9C840-044E-11D1-B3E9-00805F499D93" 
            WIDTH = "725" HEIGHT = "585" ALIGN = TOP 
            codebase="http://java.sun.com/update/1.5.0/jinstall-1_5_0-windows-i586.cab#Version=1,5,0,0">
           <param NAME = CODE VALUE = "com.sl.gmsjrtview.GmsJRtView.class" >
           <param NAME = ARCHIVE VALUE = "gmsjrtview.jar,gmsjmodels.jar,gmsjrtvreport.jar,iText.jar,J2PrinterWorks.jar" >
           <param NAME="type" VALUE="application/x-java-applet;version=1.5">
           <COMMENT><embed type="application/x-java-applet;version=1.5" 
                             code = "com.sl.gmsjrtview.GmsJRtView.class" 
                             ARCHIVE = "gmsjrtview.jar,gmsjmodels.jar,gmsjrtvreport.jar,iText.jar,J2PrinterWorks.jar" 
                             WIDTH="725" HEIGHT="585" ALIGN=TOP rtv_filename="mydisplay.rtv" 
                             pluginspage="http://java.sun.com/j2se/1.5.0/download.html">
           <noembed></COMMENT>
           <param NAME="rtv_filename" VALUE="mydisplay.rtv">
           </noembed>
           </embed>
</object>
</body>
</html>

Part i: Specify Required Applet Parameters
To host the Display Viewer Applet you must specify the following in your HMTL file:

NOTE: To specify multiple data sources for the value of the ds parameter, separate them with a ;.

Basic Required Applet Parameters
Parameter Name Description
CODE  com.sl.gmsjrtview.GmsJRtView.class

The classes specified in the CODE parameter are included in the jars specified for the ARCHIVE parameter. 
ARCHIVE  gmsjrtview.jar, gmsjmodels.jar, gmsjrtvreport.jar, iText.jar, J2PrinterWorks.jar, jar file containing custom classes.

The gmsjrtview.jar does not need to be in the directory containing the HTML file. However, if it is not, the value for the ARCHIVE parameter must contain the relative path to the jar.

gmsjmodels.jar must be copied to the directory containing the HTML file.

Multiple command users:
Add the following files (found under your installation directory in lib) to the ARCHIVE parameter:

mail.jar
activation.jar
snmp.jar

Email command users:
Add the following files (found under your installation directory in lib) to the ARCHIVE parameter:

   mail.jar
   activation.jar

SNMP Trap command users:
Add the following file (found under your installation directory in lib) to the ARCHIVE parameter:

   snmp.jar

Asian font users (that want to export reports):
Add the following file (found under your installation directory in lib) to the ARCHIVE parameter:

    iTextAsian.jar
WIDTH Set to the width of the display plus 1 pixel. The width of the display (in pixels) is noted in the Background Properties dialog. To access this information, open the file in the Display Builder, select File>Background Properties.
HEIGHT Set to the height of the display plus 41 pixels. This additional space will ensure that your display is not scaled down in size by accommodating the logo panel that appears below the applet. The height of the display (in pixels) is noted in the Background Properties dialog. To access this information, open the file in the Display Builder and select File>Background Properties.
CODEBASE If you intend to pass your applet through a portal, set the base URL for your applet (i.e.: http://<host>:<port>/<applet directory>).
rtv_filename Name of the initial display (.rtv) file to open in the Display Viewer Applet.

Applet Parameters Required for Alert Data Source
 These parameters are only required if you are using the Alert data source. NOTE: Setup is also required for any data sources you used to input data to your alerts.
Include the Alert data source in your applet:
1. Add the following to your ARCHIVE parameter (found under your installation directory in lib):
gmsjalertds.jar
2. Add the following applet parameter:
name = ds
value = com.sl.gmsjalertds.GmsRtViewAlertDs

Applet Parameters Required for Cache Data Source
 These parameters are only required if you are using the Cache data source. NOTE: Setup is also required for any data sources you used to input data to your caches.
Include the Cache data source in your applet:
1. Add the following to your ARCHIVE parameter (found under your installation directory in lib):
gmsjcacheds.jar
2. Add the following applet parameter:
name = ds
value = com.sl.gmsjcacheds.GmsRtViewCacheDs

Applet Parameters Required for Additional Data Sources

If you are using additional data sources, refer to Deployment in the Data Sources section of this documentation for required applet parameters specific to your data source. NOTE: If you are using history data you must include the SQL data source in your applet.

When finished, return to Part ii: Specify Optional Applet Parameters.

 

 

Part ii: Specify Optional Applet Parameters
Basic optional applet parameters can be specified either in your HTML file or from a configuration file (OPTIONS.ini).

  • To create in an initialization file, see Application Options.
  • To use an initialization file in your applet, include it in the directory containing the HTML file. 

NOTE: Applet parameters you specify in you HTML file will override settings in configuration (.ini) files.

The following can be specified in the applet parameters of your HTML file:

Basic Optional Applet Parameters
Parameter Name Description
confirm Set the confirm policy for all commands, overriding the confirm policy on individual objects.

Accepted values:
-1 - do not confirm any commands
 1 - confirm all commands
 0 - follow individual object confirm policy
historytablename Specify the table name (e.g., MY_TABLE) to use when loading historical data into graphs. NOTE: Table names cannot contain spaces.
nohistory Set to true to suppress historical data in graphs. Default is false.
panelconfig Specify the name of the panel configuration file for Multiple Display Panels.
rtvpass If login is enabled, specify the password in plain text to use for the login. This parameter must be used in conjunction with rtvuser and will bypass the login dialog. If the rtvrole parameter is not specified for a user with multiple roles, the first role will be used.  Use the rtvsign parameter instead to specify an encoded user name and password. 
NOTE: If the user name or password specified is not valid, the login dialog will appear.
rtvrole If login is enabled, specify the role to use for the login. This parameter must be used with rtvsign or rtvuser and rtvpass. If this parameter is not specified for a user with multiple roles, the first role will be used.
rtvsign If login is enabled, specify an encoded user name and password to use for the login, and bypass the login dialog. Contact SL Technical Support at support@sl.com to request a copy of the utility to create the encoded strings. If the rtvrole parameter is not specified for a user with multiple roles, the first role will be used. 
NOTE: If the user name or password specified is not valid, the login dialog will appear.
rtvuser If login is enabled, specify the user name in plain text to use for the login. This parameter must be used in conjunction with rtvpass and will bypass the login dialog. If the rtvrole parameter is not specified for a user with multiple roles, the first role will be used.  Use the rtvsign parameter instead to specify an encoded user name and password. NOTE: If the user name or password specified is not valid, the login dialog will appear.
singleclick Set to true to enable opening drill down windows or executing commands with a single click. Default is true.
sub Add a substitution string/value pair using the syntax substring:subvalue substring2:subvalue2

If a substitution value contains a single quote, it must be escaped using a / :

$filter:Plant=/'Dallas/'

If a substitution value contains a space, it must be enclosed in single quotes. Do not escape these single quotes:

$subname:subvalue $subname2:'sub value 2'
NOTE:  Substitution strings cannot contain the following:
:
|
.
tab
space
,
;
=
<
>
'
"
 & / \ { } [ ] ( )

timezone Set the default timezone for interpreting and displaying dates. Include a Java timezone ID or a custom ID, such as "GMT-8:00".  Unrecognized IDs will be treated as GMT.

If you run the Enterprise RTView Builder with a valid timezone parameter and then save Application Options, the timezone information will be persisted. To prevent the persisted timezone value from being used, pass "none" as the timezone ID.
update_period Set update rate in milliseconds.

 

Applet Parameters Optional for Alert Data Source

The following parameters can be specified in your HTML file, otherwise they will be read from ALERTOPTIONS.ini.
Parameter Name Description
alertds:history Sets the number of rows that are stored in the AlertTable.
alertds:alertdef Adds an alert definition file. Cannot specify substitutions. To specify substitutions, use the Application Options dialog.
alertcleartime Specifies the rate, in seconds, to remove cleared alerts. If set to greater than zero, all cleared alerts are removed every x seconds where x is the value specified.
alertinitdelay The number of seconds to wait after startup to begin executing alerts.
alertds:enabled Enables/disables all alerts in the active alert definition files.

 

Applet Parameters Optional for Additional Data Sources

If you are using additional data sources, refer to Deployment in the Data Sources section of this documentation for optional applet parameters specific to your data source.

When finished, return to Step C: Install Applet..
 

 

 C: Install Applet
At this point you have verified system requirements and configured the applet.

1. Create a project directory to store all files needed by the Display Viewer Applet.

2. Copy the following files into the directory you just created:

  • HTML file created in Step 1B

  • From the lib directory of your Enterprise RTView installation:

    • all .jar files added to the ARCHIVE parameter in Step 1B

  • From the project directory of your Enterprise RTView installation:

    • OPTIONS.ini file

    • .jar file containing custom classes (optional)

    • Panel configuration file (optional)

    • All display (.rtv) files 

    • Refer to Deployment in the Data Sources section of this documentation for information on configuration (.ini) files specific to your data sources.

    • Security configuration files (optional)

  • KEYS (see D: Register, next)

NOTE: The .jar files in the lib directory are not digitally signed. If you need to deploy with signed jars, use the jars in lib\signed-jars.zip. The certificate in these jars will expire in March of 2009.
3. Install this directory to your application server according to documentation for that product.

D: Register
At this point you have verified system requirements, configured and installed the applet.

Display Viewer Applet requires a separate license key from the Enterprise RTView application to run on a application server. Without a key, the Display Viewer Applet will run for 20 minutes to facilitate testing. No key is required to run locally.

Register Display Viewer Applet.

Step 1 is completed. Go to Step 2: Setup Report Servlet on Application Server.

Step 2: Setup Report Servlet on Application Server
At this point you have setup the applet on the application server.

Your Enterprise RTView installation includes an Apache Tomcat application server you can use to prototype and test your deployment before moving it to your production server. If you will be using this application server, the Report Servlet is already installed so you can skip to Step 3.

A: Verify System Requirements
 
  • Application server with a JSP servlet container, such as Apache Tomcat

B: Install and Setup Report Servlet
The Display Viewer Applet uses a Report Servlet to support exporting PDF reports. The servlets\rtvreport directory contains all of the files necessary to install the Report Servlet.

At this point you have verified your system requirements.

1.    In an initialized command window, go to the servlets\rtvreport directory and type:
 
make_war  This script creates a web archive (.war) named rtvreport.war that includes all of the files necessary to run the Report Servlet.
 

2.    If you will be using your own Apache Tomcat application server, type the following to install the Report Servlet:

install_to_tomcat rtvreport This script installs the web archive rtvreport.war to your Apache Tomcat server. 
NOTE: This script will shutdown and restart Apache Tomcat and requires administrative permissions.
 
  • If you will be using an application server other than Apache Tomcat, install the files in the rtvreport.war file to your application server according to the documentation for that product.

Step 2 is completed. Go to Step 3: Setup Client.

Step 3: Setup Client
At this point you have setup the applet and the Report Servlet on the application server.

A: Verify System Requirements
Each client must meet all of the following requirements:
 
  • Java Plugin 1.5.0_01+
  • Browser: IE4.0+ (other browsers also work)
  • In addition to basic system requirements, refer to the Data Sources section of this documentation for system requirements and setup specific to your data source.
  • To enable copying tables to the clipboard, the client must have the following permission on their Java security settings:
     
    permission java.awt.AWTPermission "accessClipboard";
  • In order to use the Send Email system command you must modify the Java security settings on each client to include the following permissions. Where SMTPHostName is the name of the SMTP server, SMTPHostIP is the IP address of the SMTP server and <> in the FilePermission is the name of the file to be attached to the email.
     
    permission java.net.SocketPermission "SMTPHostName", "resolve";
    permission java.net.SocketPermission "SMTPHostIP", "accept, connect, listen, resolve";
    permission java.util.PropertyPermission "user.name", "read"; };
    permission java.io.FilePermission "<>", "read";
  • The Send SNMP Trap command requires outgoing access to UDP port 162 (or a different port as specified in your command).
  •  In order to use the Topmost Window Mode on drill down windows, depending on your Security Manager, you may need to modify the Java security settings on each client to include the following permission: 
    permission java.awt.AWTPermission "setWindowAlwaysOnTop”;

B: Setup Client for Additional Data Sources
If you are using additional data sources, refer to Deployment in the Data Sources section of this documentation for information on client setup specific to your data source. NOTE: If you are using history data you must complete SQL setup.

When finished return to Step 4: Test Client.

 

Step 4: Test Client
At this point you have setup the Display Viewer Applet and the Report Servlet on the application server, and setup the client.

A: Verify System Requirements
 
  • Java Plugin 1.5.0_01+
  • Browser: IE4.0+ (other browsers also work)

B: Test
1. Open a browser and navigate to the URL for the applet you set up in Step 1.

2. Login. By default, the Display Viewer Applet requires a login to support role based security. The default user name and password are:

 User Name: admin
 Password: admin

NOTE: If your system administrator has configured a user name and password for you, use these instead. In this case, you may also need to select a role.

3. In the login dialog, enter your user name and password.

For troubleshooting information, see Display Viewer Applet Troubleshooting.


Congratulations! Enterprise RTView deployment is completed.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
   

 
SL, SL-GMS, GMS, Enterprise RTView, SL Corporation, and the SL logo are trademarks or registered trademarks of Sherrill-Lubinski Corporation in the United States and other countries. Copyright © 1998-2008 Sherrill-Lubinski Corporation. All Rights Reserved.

 
JMS, JMX and Java are trademarks and/or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. They are mentioned in this document for identification purposes only.