Browser Extension Manual

CONTENT

INTRODUCTION...... 2

SUPPORTED BROWSERS...... 2

1. INSTALLATION...... 3

1.1. FROM INTERNET...... 3 1.1.1. FOR GOOGLE CHROME...... 3 1.1.2. FOR OTHER WEBKIT BROWSERS...... 4 1.2. OFFLINE INSTALLATION...... 5 UPDATING EXTENSION TO NEW VERSION...... 5 1.4. SILENT INSTALLATION...... 6 1.5. INTEGRATION MODULE...... 6

2. CONFIGURATION...... 7

2.1. CONFIGURE SESSIONS...... 7 2.2. CONFIGURE TERMINAL...... 8 2.3. SILENT CONFIGURATION...... 9

3. MACRO AUTOMATION...... 10

4. ADVANCED DESKTOP INTEGRATION...... 11

4.1. SYNCHRONOUS BLOCKING CALLS...... 11 4.2. ASYNCHRONOUS NON-BLOCKING CALLS...... 11 4.3. WINDOWS MESSAGING...... 12 4.4. HLL TRANSPARENT COMMAND (200)...... 12 4.5. HLL SCRIPTING...... 13

GREEN SCREENS |Browser Extension Manual 1 Green Screens Ltd. GREEN SCREENS | Browser Extension Manual

IGnreternoSdcrueecntsioWneb Terminal is a browser based terminal client running inside browser isolated context which prevents terminal web application to have features commonly available in classic desktop solutions. Also, while running inside the browser, all user changes for terminal settings might be lost if browser cache is deleted.

To overcome such cases, we created a browser extension. The purpose of the extension is to enable end users to save and keep terminal settings locally without losing the data after browser cache reset, but also to enable advanced integration features with desktop apps.

Green Screens Web Terminal is the only web-based terminal with support for STRRMTCMD and IBM HLL API specification.

Supported browsers

All desktop browsers based on WebKit engine and Firefox (manual install).

NOTE: Integration modules (PCH & HLL) are available only on MS Windows platform.

List of the most common ones

 Google Chrome  MS Edge (WebKit version)  Firefox (PC)  Internet Explorer 9 (see note 2)  Opera (PC, Mobile) 12.10

GREEN SCREENS |Browser Extension Manual 2 Green Screens Ltd. GREEN SCREENS | Browser Extension Manual

1.1I.nFsrtoamllaItniotenrnet

This is the simplest method with automatic updates. It is valid procedure for companies not blocking Internet access for their employees.

NOTE: Extension will be automatically enabled at the browser toolbar when web terminal is activated.

1.1.1. For Google Chrome

To install it, open following link and click ADD TO CHROME button. https://chrome.google.com/webstore/detail/green-screens-terminal-pl/heoadinjonfifkebpcpmnkhlanbfgkem

GREEN SCREENS |Browser Extension Manual 3 Green Screens Ltd. GREEN SCREENS | Browser Extension Manual

1.1.2. For other WebKit browsers

For other browsers to be able to install extension from Google Web Store, external installation option should be enabled before installing extension itself.

Here is an example for MS Edge (WebKit version). Enable check box in bottom left corner, then open extension from link below. https://chrome.google.com/webstore/detail/green-screens-terminal-pl/heoadinjonfifkebpcpmnkhlanbfgkem

GREEN SCREENS |Browser Extension Manual 4 Green Screens Ltd. GREEN SCREENS | Browser Extension Manual

1.2. Offline installation

For workstations that does not have Internet access, it is still possible to install Web Terminal Browser Extension from Green Screens Terminal Service. Follow next steps to install Windows Registry configuration which will allow WebKit based browsers to install and update automatically from Green Screens Server.

1. Open http://localhost:9080/browser/registry (replace localhost:9080 with Green Screens Server URL) to download MS Windows Registry configuration.

2. Double click to open downloaded system file – this will create configuration inside MS Windows Registry used by WebKit browser to find an update URL and install extension.

3. Restart browser to automatically install Web Terminal Extension

NOTE: If Web Terminal service address is changed, repeat the steps to update registry configuration with new update values. Otherwise, Browser will not be able to update extension.

Updating extension to new version

There is manual update and automatic update from Google Web Store. Which mode will be used depends on user preference. If Google Web Store is not available (no Internet access), then server will not be able to update and manual mode is required.

Manual install

1. Go to http://localhost:9080/browser/ 2. Click to Download link to download latest browser extension 3. Replace extension.crx with downloaded file 4. Change extension.xml version attribute to match to downloaded version

Automatic install

Open http://localhost:9080/browser/upgrade or http://localhost:9080/browser/upgrade?async URL to start upgrade process.

If async parameter is not used, upgrade will be made in blocking mode waiting for response until process is finished.

It will start automatic download from Google Web Store and update existing version. This service will respond with blank page. Please watch server logs for information’s.

GREEN SCREENS |Browser Extension Manual 5 Green Screens Ltd. GREEN SCREENS | Browser Extension Manual

1.4. Silent installation

Silent installation is available in two flavors.

Intranet installation through registry file. Registry file can be generated from link as described in previous step. Generated registry file can be distributed through MS Windows PDC login script. When user logins, script will install registry values and when use starts a browser, browser will read those values to check for extension URL to install it if needed.

From online extension distribution facility based on documentation from this link. https://developer.chrome.com/apps/external_extensions

1.5. Integration module

Integration module (web bridge) is a part of a browser extension that enables advanced integration with desktop environment.

Features enabled with integration module are

 STRRMTCMD to start desktop application from web terminal  Direct print – enable spool web print to default or selected printer  HLL API – terminal automation specification

Mentioned features are not available inside browser directly as web pages (web terminal) are executed in browser isolated context which does not allow web page scripts to interact with underlying system.

To enable advanced features, we introduced our browser plugins which needs to be installed at the user computer and being linked to the web terminal through browser extension.

To install integration module, download 32bit or 64bit version from this link https://www.greenscreens.io/link.html

Integration module will be installed into default “C:\ProgramData\GreenScreens\Link” directory and registered into MS Windows registry for browser usage.

To enable STRRMTCMD and Direct Print, enable PCH option in extension settings page.

To enable HLL, enable HLL option in extension settings page.

NOTE: There are full and lite version. The only difference is that lite version comes without HLL. For the most cases lite version is enough.

NOTE: If only RMTCMD support is required and there are no special user permissions requirements by your organization, integration module will work without browser extension module.

GREEN SCREENS |Browser Extension Manual 6 Green Screens Ltd. GREEN SCREENS | Browser Extension Manual

2.1C.oCnofnifgiuguraretisoenssions

Once installed, open extension properties and set Green Screens Service Proxy URL. This is required for using saved session configurations.

Add session configurations (the same options as on main login page).

GREEN SCREENS |Browser Extension Manual 7 Green Screens Ltd. GREEN SCREENS | Browser Extension Manual

If session options are configured, list of configurations will be available through browser context menu from any browser tab for easy access to the Web Terminal.

2.2. Configure Terminal

To open extension options, click on extension icon and select Options.

Open Display tab to change terminal settings.

To change font size and type, open Fonts tab.

NOTE: Open extension options side-by-side with active terminal to see immediate changes.

GREEN SCREENS |Browser Extension Manual 8 Green Screens Ltd. GREEN SCREENS | Browser Extension Manual

2.3. Silent Configuration

To support large amount of workstations setup, except silent installation there is a feature for silent extension configuration. This feature allows to silently configure user extension as automatic setup for Green Service URL or for setting some of extension options silently as silent PCH activation, enter key setup, etc.

NOTE: This feature is available from extension version 4.2.1.134

Use special URL which can be called preconfigured with parameters and sent to the user through email, URL link, PDC login script or through STRPCCMD.

Main URL is: chrome-extension://heoadinjonfifkebpcpmnkhlanbfgkem/api.html

Use standard http query arguments to setup extension. For an example to activate PCH: chrome-extension://heoadinjonfifkebpcpmnkhlanbfgkem/api.html?pch=true

To add multiple values, use standard query argument format chrome-extension://heoadinjonfifkebpcpmnkhlanbfgkem/api.html?pch=true&chr=0&enter=1

Use of available arguments:

Argument value Type Description beep Boolean Enable sound signal for errors close Boolean Prevent auto closing terminal on browser close chr Numeric Crosshair mode (0, h, v, *) enter Number Enter mode (FieldExit - 1 ; Enter - 2) hll Boolean Enable HLL API id Number Client hosts configuration ID pch Boolean Enable print link url String (URL) Green Screens server URL win Boolean Enable terminal in window mode

To automatically configure terminal sessions, use web admin console to create user setups or use SQL to populate a configuration table in GREENSCRN library. Each user must have its own unique id for configurations. Use that id in URL along with Green Screens Service. Extension will populate configuration from Green Screens Server.

GREEN SCREENS |Browser Extension Manual 9 Green Screens Ltd. GREEN SCREENS | Browser Extension Manual

3Ch.roMmaecerxtoenasiountsoumppoarttsiorencording and playing screen macros for automated screen navigation. For instructions and tutorial, please visit following links on our blog.

Chrome Extension Part 1 Chrome Extension Part 2

Macros can be accessed and recorded from live terminal session as shown on image below. Click on extension icon, select camera icon to start/stop macro recording. When stopped, popup will show asking for macro name.

GREEN SCREENS |Browser Extension Manual 10 Green Screens Ltd. GREEN SCREENS | Browser Extension Manual

4NO. TAE:dTvhias nchcaeptderdisefosrkdteoveplopienrtseangdraadtviaoncned users. Browser integration module contains several desktop applications mostly responsible to support direct printing and RMTCMD.

HLL application itself enables HLL API specification to create desktop applications for accessing live terminal, send keys, data to the terminal field or to retrieve screen data. Custom developed applications communicate with HLL integration module through DLL (hll.dll).

Standard HLL API consist of a single function which operates in blocking request/response mode.

Along standard HLL API, we introduced several more features.

 Asynchronous calls (separated read and write functions)  Windows messaging  Custom transparent command (function 200)  Scripting through JavaScript for desktop (NodeJS)

NOTE: Sample JavaFX application using hll.dll can be found at link below. https://github.com/greenscreens-io/hll-client

4.1. Synchronous Blocking calls

This is classic HLL API usage. Every call to hllapi function will wait for a response from HLL integration module. In a case of error, bug, or some other reason, return from function might never happen leaving program in blocked state.

long hllapi(int func_id, string data, int data_length, int ps) 4.2. Asynchronous non-blocking calls

Classic hllapi function is divided into 2 additional functions: hllapi_read and hllapi_write. As name suggest, one for sending request and one for receiving request from HLL integration module. Format is the same as classic function. Both functions work independently of each other.

long hllapi_read(int func_id, string data, int data_length, int ps)

long hllapi_write(int func_id, string data, int data_length, int ps)

It is highly recommended to use hllapi_read in separate background thread and use callbacks or message queues internally as shown in demo application.

GREEN SCREENS |Browser Extension Manual 11 Green Screens Ltd. GREEN SCREENS | Browser Extension Manual

4.3. Windows Messaging

Messaging feature allows to forward standard MS Windows PostMessage and SendMessage API to the web terminal. This allows sending various status and signal messages from desktop application to the web terminal.

HLL integration module use custom message WM_GREENSCREENS_HLL_CLI.

Use MS Windows RegisterMessage function to register custom named message within desktop application and use retrieved message id while sending a message as a HW_BROADCAST message.

To receive messages on web terminal side, use the following example code:

Tn5250.HLL.on('message', (o) => {console.log(obj)}). 4.4. HLL Transparent command (200)

As our terminal is web based, highly extensible and can receive and process various JSON data, many new possibilities opens compared to the standard terminal clients.

Adding HLL from desktop to the web terminal integration, we realized we can add generic messaging through HLL to enable full-duplex independent communication for sending or receiving the data.

Even HLL API data argument is of a type string, binary data or JSON data can be sent through this command directly to the web terminal.

NOTE: This is intended to be used in async mode as HLL integration module or web terminal itself will always send automatic reply. Extra responses might be sent back, depending on custom protocol implementation additional read from HLL api might be required.

To receive messages on web terminal side, use the following example code:

Tn5250.HLL.on('transparent', (o) =>{ console.log(o); o.retVal=1;});

NOTE: Use retVal to change status of reply message.

To send messages to the HLL integration module, use the following example code:

Tn5250.HLL.send({data: {pid: 9064, fnid: 2, data: "A", length: 1, ps: 0, retVal: 9}})

NOTE: PID must match the requester number. Data can be any string, JSON, Base64 etc., length is length of the data.

GREEN SCREENS |Browser Extension Manual 12 Green Screens Ltd. GREEN SCREENS | Browser Extension Manual

4.5. HLL Scripting

Browser HLL integration module is a NodeJS with packaged HLL implementation scripts. As it is NodeJS, program can load external custom scripts allowing advanced users or developers to create all kind of web browser to desktop integrations.

To see some of the JavaScript examples, open Browser integration module directory at “USER\AppDAta\Local\Green Screens”

If there is a index.js file in the same directory as host.exe, application will load it. Use index.js as a standard NodeJS scripts to add custom features.

For more details how to access internal HLL API functions and how to communicate with connected clients or web terminal look for examples provided with web integration module installation.

Processing custom messages will require custom script at the browser side also. Custom initialization script can be added through Web Admin console. More details are available in Web Admin Manual document.

For testing and debugging purposes, use the following code example to catch all messages send from extension and integration module to the web terminal.

window.addEventListener("extension", (e) => { console.log(`From Extension: ${JSON.stringify(e.detail)}`); });