Programming with Reflection for the Web

  • 7022214
  • 28-Jul-2011
  • 25-Mar-2018


Reflection for the Web (All Editions)


This technical note describes a variety of options for application development in Reflection for the Web 2014 and Reflection for the Web 2011, hereinafter referred to as Reflection for the Web.


Reflection for the Web JavaScript Macro Programs

Beginning in Reflection for the Web 2011, Reflection for the Web provides the ability to create embedded JavaScript macro programs; you can record macros to play back later, or you can write macros from scratch using the Macro Editor. (In versions prior to Reflection for the Web 2011, you could record and play back macros, but not edit them.) You can use these macros to perform a variety of tasks, such as automating user interactions with the terminal, or notifying a user when various events in the terminal occur. Administrators can create macros in advance for execute-only distribution to users, or users can record and customize their own macros that are saved locally.

In addition to standard JavaScript features, Reflection for the Web macros can make use of most Java classes as well, including AWT and Swing. By default, JavaScript macros do not have Java permissions necessary to access system properties, the local file system, open sockets, etc. However, an administrator can adjust this limitation through the use of an “attachment” class. (See Reflection for the Web Scripting Help for ECLSession.addJDKScriptPermission.)

The basic user profile does not, by default, have macro access enabled. To use macros, a session must be configured for an intermediate, advanced, or custom user profile.

Documentation describing how to write a JavaScript macro is provided with Reflection for the Web from within the new Macro Editor utility available from the Macro menu, and sample macros are available in KB 7022340.

JavaScript or VBScript Hosted by Web Browsers

Embedded JavaScript macros in Reflection for the Web do not provide access to standard browser objects such as “window” or “document.” If you need to access these objects, you should use JavaScript that is included on the same page as the Reflection for the Web applet. The best way to implement this is to use a Reflection for the Web template (see KB 7022339). Use of a template allows customization of the appearance of the page hosting the Reflection for the Web applet, and makes it easy to include JavaScript or VBScript that works with the Reflection session.

There are two types of templates that can be used: a page template for sessions embedded in a browser window, or a “custom login page” template for sessions configured to appear in their own window.

Page Templates

JavaScript can be added to a .jsp file in the /rweb/templates folder that will run automatically as soon as the terminal session is fully loaded by the browser. Note the following configuration requirements:

  • When configuring a session in Session Manager, select “Display session embedded in a web browser window” and provide the name of a template .jsp file in /rweb/templates.

Samples are provided in /rweb/templates/samples. If you start with one of the sample templates, we recommend that you copy the sample to the main /rweb/templates folder; for example, copy /rweb/templates/samples/scripttemplate.jsp to /rweb/templates/scripttemplate.jsp.

  • Make sure that the session configuration includes the applet parameter preloadJSAPI=true.
  • When the applet is fully loaded, the session will automatically call a JavaScript function on the page whose signature looks like this:
function jsapiInitialized(jsapi)
  • When the session calls this function, you can perform some type of login task or screen navigation immediately, and you can save the received JavaScript API (JSAPI) object to a page level variable for later use.

Note: If different embedded sessions all have the same scripting requirement, they can all name the same template .jsp. In other words, you don’t have to have one template per session if all of the sessions need to do the same script task.

Custom Login Page Templates

Page templates provide a way to customize the page hosting the session applet. To customize the page hosting the Reflection for the Web links list applet, you can specify a “custom login page” template. For sessions that are configured to appear in their own window (as opposed to a new browser window), any JavaScript needed must be added to this type of template, since a separate page hosting the session applet will not be available. Note the following configuration information:

  • When configuring a session in Session Manager, select “Display session in its own window.”
  • Copy the sample template “customloginpage.jsp” from /rweb/templates/samples to /rweb/templates.
  • On the General tab in the Administrative WebStation Settings, enter customloginpage.jsp in the "Custom login page name (optional)" field.
  • For each framed session that needs to perform some scripting task, include the applet parameters preloadJSAPI=true and jsapiInitCallback=MySessionNameInit, where “MySessionNameInit” is the name of a unique JavaScript function for each session.
  • When the Reflection terminal applet is fully loaded, the session will automatically call a JavaScript function you add to customloginpage.jsp. The signature should look like this:
function MySessionNameInit(jsapi)

Note: A unique callback function name is necessary if multiple sessions are to perform different scripting operations because code for multiple sessions launched through the links list will be found on the same “customloginpage.jsp” page. (It is also possible to change the parameter jsapiInitCallback for embedded, browser-based sessions, but in this case there is really no need to do so.)

Alternative Methods for Using JavaScript

The Administrative WebStation help documentation discusses alternative methods for using JavaScript with Reflection for the Web sessions, for example, using "rwebapplet.getAPI("JSAPI", "SessionName");". These techniques are still available. However, using the template feature simplifies a major drawback of earlier scripting methods since it is difficult to know when the applet is fully loaded by the browser and scripted interactions with the terminal are ready to begin. Using a "jsapiInitialized(jsapi)" function in a template, along with the applet parameter preloadJSAPI=true, solves this problem because the Reflection session automatically notifies your JavaScript code as soon as the session is fully loaded and ready to work with.

Another technique for having the session notify your JavaScript code upon session initialization uses the Reflection “JSEventNotifier” object, which is documented in the Reflection for the Web SDK (RWebSDK). This object provides some advanced features not present in the “JSAPI” object, however, these are not likely to be required by the majority of scripting tasks.

Documentation for the JSAPI object is included with the Reflection for the Web Administrative WebStation, and the RWebSDK is available in a zip file on the product CD. It is also available as a separate download in the Maintenance Entitlements section at

Java Attachment Classes

It is possible to create a Java class that performs the same function as a JavaScript macro, then package it, digitally sign it, and have it automatically delivered to the browser along with the rest of the Java classes that make up a Reflection for the Web session. To use this technique, create a new class that implements ECLAppletInterface and the method init(ECLSession). After the class is loaded and the init method is called, the class will receive a reference to the current terminal session as an ECLSession object, and it can perform whatever tasks are desired. A class “attached” to the session like this can be launched in several ways:

  • When the session first starts, or when it closes.
  • A toolbar button, keystroke, or button palette button can be set to run the class.
  • A JavaScript macro that calls ECLSession.loadJavaClass().
  • A JavaScript function on the applet page that calls ECLSession.loadJavaClass().

The advantage to using an attachment class is the ability to leverage the full range of possibilities afforded by the Java platform. Since Java classes are compiled into a binary format, this enables you to keep end users from seeing the code being executed (in contrast, code is visible when using JavaScript). However¸ there are quite a few steps involved in creating this kind of Java class; you must compile it, package it, and deploy it, and configure Reflection for the Web to use it. Java programming experience is required.

Comprehensive documentation discussing how to create, package, and deploy attachment classes is found in the Reflection for the Web SDK.

Java Standalone Applets

You can create a new Java applet providing whatever custom user interface you wish, and this applet code can create a new ECLSession object to connect to a host system. The ECLSession object, transparent to the end user, can be driven through code to collect host data or send input as necessary, and any result can then be displayed using your own custom applet interface. An HTML page containing an applet tag for this custom applet will be kept on the Reflection for the Web server, and optionally, the access to the applet can be controlled by the Reflection for the Web management server just as regular sessions are. For more information, see the Reflection for the Web SDK.

Java Standalone Applications

The Reflection for the Web SDK provides a single .jar file, RWebSDK.jar, that contains all classes that make up the Reflection for the Web Emulator Class Library. Normally, this .jar is used only by Java programmers while developing and testing attachment classes and standalone applets. However, it is possible to use the RWebSDK.jar to create a Java terminal emulation application based on Java frame or window classes with no dependency on the Reflection for the Web server. Documentation about this type of application is in the Reflection for the Web SDK, and example code is available from the Attachmate Download Library:

Note: Each desktop to which this kind of application is distributed must be a licensed Reflection for the Web user.

Additional Information

Legacy KB ID

This document was originally published as Attachmate Technical Note 2570.