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 Served Data - Deployment Process for a summary of these instructions.

These instructions are intended for users with standard working knowledge of servlet deployment, HTML code and application server administration. If you do not have a full understanding of these, 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 Data Server
Install Enterprise RTView on the system where you will run the Data Server.

A: Verify System Requirements
 

Java 1.5.0_01+ Accessible over the network to the Data Servlet. 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. NOTE: The Data Servlet must have permission to access the Data Server on the port specified for the socket in the DATASERVER.ini file (see Step D: Configure Data Server).

B: Install and Setup Enterprise RTView
At this point you have verified your system requirements.

1. Install Enterprise RTView

2. Setup Enterprise RTView

C: Register
At this point you have installed and setup Enterprise RTView.

Register for a license for the Data Server.

D: Configure Data Server
At this point you have installed, setup and registered your Enterprise RTView installation.

1. Create a project directory to store Data Server configuration files.

2. Copy the following files into the directory you just created from the project directory where you developed your Enterprise RTView application:
 

OPTIONS.ini file Refer to Deployment in the Data Sources section of this documentation for information on configuration (.ini) files specific to your data sources. All display (.rtv) files you want to preload (optional)

3. If you already created a DATASERVER.ini that is configured to run the Data Server in socket mode on the correct port, copy the DATASERVER.ini to the project directory created in Step D1. Then go to Step 2: Setup Data Servlet on Application Server.

If you have not created a DATASERVER.ini, go to next step.

4.  In an initialized command window, go to the project directory you created in Step D1 and type:

run_dataserver -socket

NOTE: The Data Server must be configured to run on a socket. The port specified for the socket must match the ServicePort specified for the Data Servlet in Step 2B.

6. Click the Save Configuration button to save DATASERVER.ini and exit the Data Server.

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

Step 2: Setup Data Servlet on Application Server
At this point you have completed the Enterprise RTView installation and setup, and configured the Data Server.

A: Verify System Requirements
 

Application server with a JSP servlet container, such as Apache Tomcat Must have permission to access the Data Server on the port specified for the socket in   DATASERVER.ini (see Step 1D)

B: Install and Setup Data Servlet
The Data Server uses a Data Servlet that runs on your application server. The Data Servlet communicates with the Data Server via a socket and communicates with the clients via HTTP or HTTPS. The servlets\rtvdata directory contains all of the files necessary to configure and install the Data Servlet.

At this point you have verified your system requirements.

1. Configure Data Servlet Options
The Data Servlet reads servlet.properties to get configuration information. If you have not installed the Data Servlet, modify the servlet.properties files in the servlets\rtvdata directory and it will be installed as part of the next step. If you have already installed the Data Servlet on your application server, you can edit this properties file in your application server. You may need to restart your application server after making changes to this file.

You can set the following options in servlet.properties:

Option	Description
ServiceHost	The name of the host on which the Data Server is running. Default is localhost. NOTE: Default localhost assumes the servlet and Data Server are running on the same machine.
ServicePort	Port for communicating with the Data Server. Default is 3278.  *This must match the port specified in the Data Server (Step 1D-5).
ServiceTimeout	Amount of time (in seconds) the servlet will wait for replies from the Data Server. Default is 15 seconds.

The following is an example of the servlet.properties file:

ServiceHost=localhost
ServicePort=3278
ServiceTimeout=15

2. Install the Data Servlet
 

In an initialized command window, go to the servlets\rtvdata directory and type:

 

make_war

This script creates a web archive (.war) named rtvdata.war that includes all of the files necessary to run the Data Servlet.

 

Your Enterprise RTView installation includes an Apache Tomcat application server, so that you can prototype and test your deployment before moving it to your production server. If you will be using this application server, type the following to install the Data Servlet:

 

install_to_demoserver rtvdata

This script installs the web archive rtvdata.war to the Apache Tomcat server included in your Enterprise RTView installation. NOTE: This script will shutdown and restart Apache Tomcat and requires administrative permissions.

 

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

 

install_to_tomcat rtvdata

This script installs the web archive rtvdata.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 rtvdata.war file to your application server according to the documentation for that product.

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

Step 3: Setup Report Servlet on Application Server
At this point you have completed the Enterprise RTView installation and setup, configured the Data Server and setup the Data Servlet.

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 4.

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:

Step 3 is completed. Go to Step 4: Setup Applet on Application Server.

Step 4: Setup Applet on Application Server
At this point you have installed and setup Enterprise RTView, configured the Data Server, setup the Data Servlet and the Report Servlet.

A: Verify System Requirements

• Application server
  NOTE: This must be the same application server where you installed the Data Servlet in Step 2.

B: Configure Applet
In this section you 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.

NOTE: 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, index.html, contains the Display Viewer Applet which is in your installation directory under demos/esphere. The minimum HTML code required to run the Display Viewer Applet:
 

<html> <body> <object classid="clsid:8AD9C840-044E-11D1-B3E9-00805F499D93"         WIDTH="937" HEIGHT="665" ALIGN=TOP         codebase="http://java.sun.com/update/1.5.0/jinstall-1_5_0-windows-i586.c ab#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">         <param NAME="rtv_filename" VALUE="top.rtv"         <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="937" HEIGHT="665" ALIGN=TOP rtv_filename="top.rtv"                 dataserver="remote:3278"                  pluginspage="http://java.sun.com/j2se/1.5.0/download.html">         <noembed></COMMENT>         <param NAME="dataserver" VALUE="remote:3278">         </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:

• basic required applet parameters; and
• applet parameters required for the TIBCO EMS Manager application.

Applet Parameters Required for the TIBCO EMS Manager NOTE: These parameters are only required if you are deploying the TIBCO EMS Manager application.

1. Add the following file (found under your installation directory in lib) to the ARCHIVE parameter: gmsjemsmgr.jar 2. Include the following TIBCO EMS jars, tibjms.jar, jms.jar and tibjmsadmin.jar, in your ARCHIVE parameter if you would like to execute administration commands from the following TIBCO EMS Manager Displays: Manage Topics (manage_topics.rtv) Manage Queues (manage_queues.rtv) Manage Durables (manage_durables.rtv) Manage Routes (manage_routes.rtv)

Part i is completed. Go to Part ii: Specify Optional Applet Parameters.

Part ii: Specify Optional Applet Parameters
You can specify the following parameters either in the applet parameters of your HTML file or from OPTIONS.ini. Applet parameters specified in the HTML file will override settings from OPTIONS.ini.

1. Create an OPTIONS.ini file, by going to Application Options. You will use this file in Step C: Install Applet.

If you already have an OPTIONS.ini file, go to the next step.

2. Include OPTIONS.ini in the directory containing the HTML file and see the following instructions.

The following options are read from OPTIONS.ini if they are not included in the 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.
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.

C: Install 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 3B   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  Security configuration files (optional)   KEYS (see Register below) 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
The Display Viewer Applet requires a separate license key from the Enterprise RTView applications to run on an 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 4 is completed. Go to Step 5: Start / Run Data Server.

Step 5: Start / Run Data Server
At this point you have installed and setup Enterprise RTView, setup the Data Servlet, Report Servlet and the Display Viewer Applet.

1. In an initialized command window, go to the directory you created in Step 1D and type:
 

run_dataserver

2. Click the Start Serving Data button.

NOTE: You may also run the Data Server as a daemon process. See Running the Data Server for more information and additional options.

NOTE: The Data Server is instrumented with JMX to allow you to manage and monitor the clients and application settings. See Managing the Data Server Using JMX for more information.

Step 5 is completed. Go to Step 6: Test Data Servlet.

Step 6: Test Data Servlet
At this point you have installed and setup Enterprise RTView, setup the Data Servlet, the Report Servlet, and the Display Viewer Applet, and started the Data Server.

1. Open a browser and navigate to the test.jsp file included in the rtvdata.war:
 

http://host:port/rtvdata/test.jsp?test=1

Where host and port are where the Data Servlet is running.

2. Verify that the Data Servlet is running. The browser should display text similar to the following:

GmsServlet: running
POSTs: 0
Service:
host: localhost
port: 3278
connected: false

Service should reflect the configuration that is entered in servlet.properties and connected should be true if the Data Servlet is connected to the Data Server.

Step 7: Test Client
At this point you have installed and setup Enterprise RTView, setup the Data Servlet, the Report Servlet and the Display Viewer Applet, started the Data Server and tested the Data Servlet.

A: Verify System Requirements
 

Java Plugin 1.5.0_01+ Browser: IE4.0+ (other browsers also work) 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:   permission java.net.SocketPermission "SMTPHostName", "resolve"; permission java.net.SocketPermission "SMTPHostIP", "accept, connect, listen, resolve"; permission java.util.PropertyPermission "user.name", "read"; }; Where SMTPHostName is the name of the SMTP server, SMTPHostIP is the IP address of the SMTP server. NOTE: Email attachments are not supported in the Display Viewer Applet.    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: Test
1. Open a browser and navigate to the URL for the applet you set up in Step 3B.

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.

For troubleshooting information, see Display Viewer Applet Troubleshooting.

Congratulations! Enterprise RTView deployment is completed.