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

This section is intended for users with standard working knowledge of HTML, JSP and servlet deployment on an application server.

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: Install and Configure Display Server
Install Enterprise RTView on the system where you will serve the applet.

A: Verify System Requirements

Java 1.5.0_01+ 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. Requires a graphics context in order to run and therefore cannot run on a headless server.

B: Install Display Server
At this point you have verified your system requirements.

1. Install Enterprise RTView

2. Setup Enterprise RTView

C: Register
At this point you have verified your system requirements and installed the Display Server.

Register for a license to run the Display Server.

D: Configure Display Server
At this point you have verified your system requirements, and installed and registered Enterprise RTView.

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

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

All display (*.rtv) files OPTIONS.ini Refer to Deployment in the Data Sources section of this documentation for information on configuration (.ini) files specific to your data sources. Panel configuration file (optional) Security Configuration files (optional) DISPLAYSERVER.ini NOTE: If you have no DISPLAYSERVER.ini file, create one in Step 3. Otherwise, go to Step 4.

3. Set Display Server options. Create DISPLAYSERVER.ini in the directory you just created with the following options:

Option	Description
display_timeout	Amount of time, in seconds, that a display can be kept in memory after the Display Servlet has stopped requesting it. Default is 60 seconds (to allow faster load time when switching between displays).
imageformat	Specify image format: jpg or png. If imageformat is not specified, the Display Server will automatically select the image that results in the fewer number of bytes for each display. By default the png format will be selected for most displays, but the jpg format is preferred for: a background image in the main display background images in graphs or labels images with color gradients (especially those with lower imagequality values).
imagequality	A value between 0 and 100 which controls the quality of the generated images. If the value is 100, the Display Server outputs the highest quality image with the lowest compression. If the value is 0, the Display Server outputs the lowest quality image using the highest compression. Default is 75.
history_config	To preload a display, making data immediately available. Preloaded displays are not unloaded unless the Display Server is restarted or the display cache is cleared via JMX. This option may be used multiple times to specify multiple displays to preload: history_config rtvFileName substitution Substitutions are optional and must use the following syntax: $subname:subvalue $subname2: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' A substitution string cannot contain the following: : | . tab space , ; = < > ' " & / \ { } [ ] ( )
max_displays	Number of displays kept in memory. Default is 20 (to optimize memory used by the Display Server).
passclientlogin	If true, pass Enterprise RTView login information into all data sources that have the Use Client Credentials option enabled. NOTE: Some data sources do not support this feature. For information on Application Options for your data source, refer to the Data Sources section of this documentation.
port	Port that the Display Server uses to communicate with the Display Servlet. Default is 3279.  NOTE: If you will be running multiple Display Server applications on the same application server, you must specify a unique port for each application.

Example of the above options set in the DISPLAYSERVER.ini file:

display_timeout 60
imagequality 75
history_config trend1.rtv
max_displays 20
port 3279
passclientlogin false

User Name: admin
Password: admin

To use this security feature, do the following:
1. Define the users that can access Enterprise RTView, assign each user a password and one or more associated roles. If your user definitions are in an XML file, copy this file to the directory you created in Step D1.

2. Set role definitions to specify which displays users can access. If your role definitions are in an XML file, copy this file to the directory you created in Step D1.

3. Enable the Use Client Credentials option if you want to pass Enterprise RTView login user name and password to database connections. NOTE: Some data sources do not support this feature. For information on Application Options for your data source, refer to the Data Sources section of this documentation.
 

Use the -passclientlogin command line option or the passclientlogin option (see Step 1D-3) in the DISPLAYSERVER.ini configuration file to pass Enterprise RTView login into these database connections.

Step 1 is completed. Go to Step 2: Configure and Install Display Servlet.

Step 2: Configure and Install Display Servlet
At this point you have completed the Enterprise RTView installation and setup.

About Display Servlet
The Display Server uses the Display Servlet, a JSP servlet that runs on your application server. Clients communicate with the Display Servlet using HTTP. The Display Servlet communicates with the Display Server via socket to request HTML for display in the browser. The servlets\rtvdisplay directory contains files (JSP, HTML, classes, properties) necessary to install the Display Servlet.

A: Create Display Servlet HTML or JSP Files
The Display Servlet comes with a few HTML files for testing. You can use these to deploy, or you can create your own HTML or JSP files which make calls to the Display Servlet to show your displays.

Skip this step and go to Step B: Configure Display Servlet Options if both of the following are true: You will only be deploying one Display Server application on your application server You want to deploy using only the test HTML files that come with the Display Servlet
NOTE: If you skip this step, use servlets\rtvdisplay as your project directory referenced in Steps B and C, and use rtvdisplay for the appname argument for all of the scripts.

Otherwise, proceed with the following steps.

1. Create a project directory to store your Display Servlet files.

2. Copy rtvdisplay.properties into this directory from servlets\rtvdisplay.

3. Create the HTML files or JSP files for your Display Server application.

4. Copy these HTML or JSP files and any referenced files (e.g., images referenced in the HTML files) to this directory.

5. Copy sample_make_war.bat (for Windows) or sample_make_war.sh (for UNIX) into this directory from servlets\rtvdisplay and rename it to make_war (with the appropriate extension).

6. This script takes a name for the web archive, without the .war extension, and builds a web archive file that includes all of the necessary Enterprise RTView Display Servlet files along with all .html, .js, .gif and .jpg files from the current directory. If there are other files you would like to include in your web archive, add them to the following line in your make_war script:

        jar uf %1.war *.html *.jpg *.gif *.js *.jsp WEB-INF

NOTE: You may receive an error message if the script does not find at least one of each of the file types specified (.html, .jpg, etc). Disregard this error message.

B: Configure Display Servlet Options
The Display Servlet reads rtvdisplay.properties to get configuration information. If you have not installed the Display Servlet, modify the rtvdisplay.properties files in your project directory and it will be installed as part of the next step. If you have already installed the Display 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.

Use servlets\rtvdisplay as your project directory if you skipped Step A: Create Display Servlet HTML Files.

Set the following options in rtvdisplay.properties:

Option	Description
DisplayServerHost	The name of the host on which the Display Server is running. Default is localhost. NOTE: Default localhost assumes the Display Server and Display Servlet are running on the same application server.
DisplayServerPort	Port for communicating with the Display Server. Default is 3279. This must be the same port specified in your DISPLAYSERVER.ini, created in Step 1D-3.  NOTE: If you will be running multiple Display Server applications on the same application server, you must specify a unique port for each application.
DisplayServerTimeout	Amount of time (in seconds) the Display Servlet waits for replies from the Display Server. Default is 15 seconds.
DefaultRefreshInterval	Rate (in seconds) at which displays are refreshed. Default is 15 seconds. Set this interval to 0 if you do not want displays automatically refreshed. NOTE: The refresh rate specified in the rtvRefreshInterval property or the URL or DIV tag used to open a display will override this value.
LoginEnabled	Set to true to enable role management security. If enabled, a login dialog will appear when the client browses to the URL for the Display Servlet, unless single sign-on is configured. The default is false.
VirtualThreshold	Set the cell count of a table at which point Virtual Mode is used. Default is 500.  For smooth scrolling, data is preloaded into tables with less than 500 cells. For tables with more than 500 cells, Virtual Mode is used in which data is paged into the tables to speed processing time for displaying, refreshing and sorting. However, the table may blink while scrolling in this mode.

Example of the rtvdisplay.properties file:

DisplayServerHost=localhost
DisplayServerPort=3279
DisplayServerTimeout=15
DefaultRefreshInterval =15
LoginEnabled=true
VirtualThreshold=500

If you skipped Step A: Create Display Servlet HTML Files, use servlets\rtvdisplay as your project directory and rtvdisplay as your appname in this step.

Otherwise, use the project directory that you setup in Step A and your web archive file name for appname.
NOTE: If you will be running multiple Display Server applications on the same application server, each application must have a unique name.

1. In an initialized command window, go to your project directory and type:
 

make_war appname

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

2. 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, run the following script to install the Display Servlet:
 

install_to_demoserver appname

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

3. If you will be using your own Apache Tomcat application server, run the following script to install the Display Servlet:
 

install_to_tomcat appname

This script installs the web archive to your Apache Tomcat server.  NOTE: This script will shutdown and restart Apache Tomcat and requires administrative permissions.

4. If you will be using an application server other than Apache Tomcat, install the files in the web archive to your application server according to the documentation for that product.

Step 2 is completed. Go to Step 3: Configure and Install Display Server Portlet (Optional).

Step 3: Configure and Install Display Server Portlet (Optional)
At this point you have setup the Display Server and the Display Servlet.

The Display Server can optionally be deployed as a portlet. The portlet is tested in Liferay and contains configuration files specific to Liferay, but should work with any JSR-168 compliant portal. If you want to deploy the Display Server as a servlet, skip this step and go to Step 4: Run Display Server.
 

A: Configure Display Server Portlet Options
The servlets\rtvportlet directory contains all of the files necessary to install the Display Server portlet. It includes a web.xml and several other configuration files necessary for use in a Liferay portal. Make any necessary changes to thesse files, or if you are using another JSR-168 compliant portal, copy any required configuration files to this directory. The Display Server portlet requires the Display Servlet to run and will access it at http://host:port/rtvdisplay, where host and port are the host and port where the portlet is running.  If this is not the case, modify the value for the rtvServletUrl parameter in portlet.xml to point to the correct location of the Display Servlet. Rebuild the rtvportlet.war file using the make_war.bat script.
 

B: Install Display Server Portlet
Install servlets\rtvportlet\rtvporlet.war to your portal according to the documentation for that product.
 

C. Instance the Display Server Portlet in Your Portal
Once the Display Server portlet is installed to your portal, you can instance it according to the documentation for that product. The Display Server portlet supports edit mode and view mode. In edit mode, you can specify the display, refresh rate, window name, width and height for the portlet.

Step 3 is completed. Go to Step 4: Run Display Server.

Step 4: Run Display Server
At this point you have setup the Display Server and the Display Servlet, and (optionally) setup the Display Server Portlet.

A: Start Display Server
1. Start the Display Server. Open an initialized command window and go to the directory created in Step 1 and type:
 

run_displayserver

Java options specified in RTV_JAVAOPTS are used by the run_displayserver scripts.

See Appendix C for available command line options.

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

Step 4 is completed. Go to Step 5: Test Client.

Step 5: Test Client
At this point you have setup and started the Display Server, and setup and installed the Display Servlet.

1. Open a browser and navigate to the URL for the Display Servlet you set up in Step 2. For example:
 

http://host:8080/rtvdisplay/index.html

Where host and port are correct for the application server hosting the Display Servlet.

2. Login and open a browser to the URL for your Display Servlet. By default, the Display Server requires a login to support role based security. If login is enabled to support role based security, the default user name and password are:

User Name: admin
Password: admin

Problem: An error message appears in the browser.
Solution: Check the command window where you started the Display Server as well as the Display Servlet log file on your application server.

• Combo Box
• Checkbox
• Text Entry
• List Box
• Push Button
• Slider

• Zoom: zoom-in by dragging in trace area, zoom-out by Shift+Click.
• Scrolling: live scrolling through time range
• Cursor: slide horizontally to see interpolated data values in legend
• Data Tips: text boxes with data info popup when mouse is over a data point
• Legend: can be positioned above, below, right, or left of trace area. The legend can be resized interactively, and clicking on a trace's legend entry toggles the visibility of the trace.

2. Hold down the <Shift> key while you right-click to bring up the web browser's popup menu.

3. Logout by right-clicking and selecting Log Off before closing the web browser. Some web browsers may not logout the user after the browser window has been closed.

Threshold commands are not supported in the Display Server, as well as the following commands:

• Beep
• Play Audio File
• Run DOS Command or UNIX Shell

The commandCloseWindowOnSuccess property is not supported in the Display Server.

The Display Server does not support command failure notification on the client. Notification only appears as a console message on the server.

Drill down displays have the following limitations:

• The Topmost Window Mode has no effect in the Display Server, it is equivalent to the Normal setting.
• If the user clicks outside of a display from which a drill down in Modal Window Mode was opened, but still within the same browser instance (i.e.: in another frame or iframe), the modal drill down may be obscured. When the mouse is moved across or clicked in the parent display, the modal drill down will return to the top.
• In Modal Window Mode the user can close the main browser window without first closing the drill down window.
• If the Window Position specified is completely off-screen, the coordinates will be adjusted so that the window is partially on-screen.
• If the Window Position is set to Center of Screen or Center of Parent the window open slightly lower than expected.
• In Firefox, when drill down window is closed the next mouse click in the parent window may be ignored.

Table Objects
The Display Server generates JavaScript to display table objects (obj_table02). The JavaScript table has the following limitations:

• The scrollbarMode, tabIndex and editDataEnabledFlag properties are ignored. The default values are used.
• The minimum requirements for viewing in a web browser are Internet Explorer 5.5, Netscape 7.1 and Firefox 1.0.
• For smooth scrolling, data is preloaded into tables with less than 500 cells. For tables with more than 500 cells, Virtual Mode is used in which data is paged into the tables to speed processing time for displaying, refreshing and sorting. However, the table may blink while scrolling in this mode. To modify, use the VirtualThreshold property in rtvdisplay.properties.
• If a sort column is configured in the table object in the Display Builder, the sort icon does not appear in the column header when viewed in the Display Server. The sort icon appears if the sort column is selected at the time the Display Server is started.

Table object (obj_table02) has the following limitations:

• When the multiSelectFlag property is enabled:

• Multiple rows can only be selected using Ctrl+Left click.
• A mouse click must be used to select columns.
• A right-click does not select a row under the mouse pointer
• Once a table is displayed, changes to the value of the multiSelectFlag property are ignored.
• In Firefox, a double right-click must be used to open popup menus.

• When the indexColumns property is enabled it is ignored. Also, a selection made in the table gets cleared if the number of rows in the table changes after a data update.
• The columnResizeEnabledFlag cannot be toggled.
• The rowHeaderEnabledFlag cannot be toggled.

Graph Objects

• The scrollbarSize property is ignored. The system default value is used.

Object Grid

• The scrollbarSize property is ignored. The system default value is used.

Slider Control

• The Slider Control (obj_c1scale) is drawn as a scrollbar rather than a slider.
• The updateWhileAdjustingFlag, bgColor, and objHeight properties are not supported.
• The enabledFlag property is not supported in Firefox.

Button Control

• In Firefox, the defaultButtonFlag is ignored unless a control object in the display has focus.

Combo Box Control

• The textEditEnabledFlag property is not supported.

Generated HTML controls have the following limitations:

• Control objects are generated with your browser's default font and color settings. The bgColor and valueTextFont properties are ignored.
• In older browsers that do not support CSS, HTML control objects may not be positioned correctly and appear outside the image.
• Control objects are reset to their initial values when a Drill Down is executed. To display the current value, attach the selectedValue property to a variable or Get Substitution function for the substitution set.

The Fx graph objects have the following limitations:

• The Fx graph objects can be resource intensive during display loading and updating. This should be kept in mind when designing displays. A display containing several Fx graph objects may load slowly.
• If the context menu is opened near an Fx graph object, the menu will be partially hidden by the Fx graph. 
• A right-click inside an Fx graph object will open the Flash Player menu, not the Thin Client's context menu.

Test Displays
Two HTML files are included in the rtvdisplay.war for testing. You can also open a display by entering the JSP directly in the URL.

1. Open index.html (e.g., http://host:port/rtvdisplay/index.html).

In the left frame of index.html is a list of display (.rtv) files available in the directory where you started the Display Server. The main frame should show the selected display.

2. Open panels.html (e.g., http://host:port/rtvdisplay/panels.html).

The panels.html file arranges multiple display panels in frames according to your panel configuration file. If the panel configuration file is not found in the project directory where you are running the Display Server, the Display Server searches under lib in your installation directory. See the Multiple Display Panels section for information on creating panel configuration files.

NOTE: The CardPanel and GridPanel are not currently not supported in the Display Server.

3. Specify the panel configuration file name and the border width (in pixels) in the URL:

4. To specify a display to open in the URL:

5. Specify substitutions to apply to your display and a refresh rate (in seconds) which overrides the DefaultRefreshRate in rtvdisplay.properties (specified in Step 2A):
 

NOTE: To specify multiple substitutions, separate them with a + (plus). If a substitution value contains a single quote, escape it with a / (forward slash). If a substitution value contains a space, enclose it in single quotes (do not escape these quotes) and replace the space with a +.

Congratulations! Enterprise RTView deployment is completed.