EWD.js and VistA: Adding a JavaScript Terminal

In this final article in the series on the integration of EWD.js and VistA using Christopher Edwards’ OSEHRA Installer, I want to introduce what I believe is a critically important new component: a JavaScript-based VT-100 terminal emulator that can run within a browser.  This is integrated with a back-end Node.js module that acts as a relay between the WebSockets interface of the terminal emulator and the SSH interface of the actual back-end terminal process.

I can’t take credit for the actual browser-side terminal emulator: it’s based on Christopher Jeffrey’s term.js Open Source project.  However, I’ve made a number of amendments to it that allow it to work satisfactorily with the versions of Internet Explorer that are used by the US Dept of Veterans’ Affairs (VA).  I also designed and built the back-end interface so that it would correctly and securely inter-operate with VistA running on both Linux and Windows platforms using Caché and GT.M databases.

The importance of this JavaScript terminal is that without it, a progressive migration to browser-based VistA applications and enhancements will, despite the many advantages and innovations that will be possible in such migration, be hindered by the inconvenience for the user of constantly having to switch between the browser and a terminal.  Clearly once all VistA applications have been migrated, the terminal becomes an irrelevant non-issue.  However, it will  be some time before all the legacy roll & scroll applications of VistA are replaced and no longer needed, so it’s important to plug that gap now.

My EWD VistATerm project provides a 100% Open Source solution to bridge this immediate-term gap.

So, without further ado, let me take you through the steps needed to install and configure the terminal on your EWD.js / VistA system.

Installing EWD VistATerm

Installing it is simply a matter of copying and pasting the following commands (I’d recommend one by one) into your terminal/puTTY session.  (I’m hoping that Chris Edwards will include these (or their equivalent) steps into his next iteration of the OSEHRA Installer).

1) You need to be logged in as username osehra in order to perform this installation. If you’re running on an EC2 server, you can do this as follows:

sudo su - osehra

2) Install the terminal module:

cd node
npm install ewdvistaterm

3) Move the browser-side components into place under the /home/osehra/www/ewdVistATerm directory:

cd ~/www
mkdir ewdVistATerm
cp -r ~/node/node_modules/ewdvistaterm/terminal/* ~/www/ewdVistATerm/

4) Move the pre-built startup file for the VistATerm back-end into the /home/osehra/node directory. This startup-file has been specifically designed for use with the EWD.js/VistA system that you’ve installed, but it can be easily adapted for any other system configuration.

cp ~/node/node_modules/ewdgateway2/ewdLite/OSEHRA/VistATerm.js ~/node/VistATerm.js

Christopher’s installer has already created a special username – osehratied – for use with the terminal: this username is tied directly into the ^ZU application within VistA.

If you’re running your EWD.js/VistA system on an EC2 machine, then normally, you’d assign a key-pair to this user: you can, of course, do this if you know the steps to do so. It’s a bit of a rigmarole to describe, so for brevity’s sake, I’m going to use a quicker and simpler (if less secure) approach which involves reconfiguring the SSH daemon to allow passwords.

So you need to edit the file /etc/ssh/sshd_config.

First, switch back to the ubuntu username:


To edit the file, I use the nano editor:

sudo nano /etc/ssh/sshd_config

but you can use the editor of your choice: just make sure you do it as sudo in order to have the permissions to change this system file.

Once you’re in the editor, search through the file for the line:

PasswordAuthentication no

and change it to:

PasswordAuthentication yes

Save the file and restart the SSH daemon:

sudo reload ssh

One final step: the ssh command doesn’t allow you to programmatically log in a user using his/her username and password. However, there’s a nice alternative named sshpass that can come to our rescue. The pre-built startup file for the EWD VistATerm back-end already assumes we’ll be using sshpass. So let’s now install it:

cd ~
sudo apt-get install sshpass

Starting the VistATerm Back-end Process

We’re now ready to fire it up. Switch back to the osehra username and start the back-end VistATerm process as follows from within a terminal/puTTY session:

sudo su - osehra
cd ~/node
node VistATerm

This process is now listening for activity on port 8081.

We’re now ready to try out the terminal. Initially we’ll try it out in standalone mode within your browser. Enter the following URL (adjust the EC2 domain name as required):


The first time you try this, it might just give a warning message. If so, just reload the URL in the browser – you shouldn’t see that warning again.

What you should see is a terminal session appearing in your browser.  The tied user has gone straight into VistA and is asking for an Access Code:

Screen Shot 2014-03-03 at 08.46.45

Try logging in using a valid Access & Verify Code (eg fakedoc1 / 1Doc!@#$) – you should find that it behaves exactly as you’d expect and you’ll be able to run all the standard Roll & Scroll and ScreenMan legacy VistA applications!

When you finally exit (or let it time out), the back-end SSH process is halted and it will no longer respond to any characters that you type.  Just reload the URL to start it again.

Integrating the Terminal into a Bootstrap 3 Application

Now that you have successfully tested the terminal, you can now see what it looks like when it’s integrated into a Bootstrap 3 application.  Eagle-eyed readers of my third article in this series which looked in detail at the VistADemo application will have noticed (and perhaps tried out) a navigation option on the header bar labelled Terminal.  It won’t have worked when you tried it then.  However, it will work now!

So, bring back the VistADemo application by using the URL (once again adjust the domain name appropriately):


Login using a valid Access/Verify Code pair (eg fakedoc1 / 1Doc!@#$) and click away from the patient selector panel. Now click the Terminal option in the header bar and you should see the terminal running as a panel within the Bootstrap 3 application:

Screen Shot 2014-03-03 at 08.59.19

Try switching between the Main and Terminal navigation options: you can see how easy it now is to switch between the brave new browser-based world and the old roll & scroll world, without leaving the browser.

How is this done?  You have all the source code available to you.  You need to look in two places:

  • the terminal application is integrated by using an iframe.  This is loaded into the VistADemo application via the fragment file /home/osehra/www/ewd/VistADemo/terminal.html
  • The terminal application is loaded into the iframe via a simple onFragment handler function in /home/osehra/www/ewd/VistADemo/app.js:
'terminal.html': function(messageObj) {
  var url = 'https://' + $(location).attr('hostname') + ':' + EWD.VistATerminalPort + '/ewdVistATerm/term.html';
  $('#terminalFrame').attr('src', url);

That’s all there is to it!

Notice, by the way, that the terminal application is loaded over SSL/HTTPS. This means that the WebSocket messages are also running securely over SSL: in other words, VistATerm is safe to use within a browser and all its traffic will be encrypted.

Stateless versus Stateful

There’s an important difference between the browser-based new applications built using EWD.js and the VistATerm terminal sessions that run within the browser.

The former are stateless applications, meaning that they are not tied to a specific back-end process for each user.  Instead, EWD.js uses a very small number of back-end processes to handle all the activities of potentially many thousands of users.  Such stateless design is the key to high-end scalability.  The system resources, in particular memory requirements, of the server are significantly reduced and used much more efficiently.  You no longer need a process for each user, with each process requiring its own quota of memory to support the activities of just that user.

If you think about it, even on a very busy system with many thousands of concurrent users, at any one moment in time, most of those users are probably actually not doing anything, at least in terms of using system resources: they’re looking at the screen, moving the mouse around, deciding what to do.

In a stateless architecture,  a very small number of processes are used to handle the work of the minority of users who are actually doing something at any moment in time.  Those processes are used very heavily but very efficiently.

By comparison, every time you bring up the VistATerm application, it’s having to start up an individual process for that user – terminal sessions are stateful.  Ultimately they are a wasteful and expensive way of using system resources.

This is why the terminal integration should be seen as only a short-term stop-gap measure.  High-end performance and scalability will be achieved to migrating as much as possible to new stateless EWD.js browser-based applications.


This article concludes this series which has introduced the many important and powerful capabilities of EWD.js and its supporting technologies.  For those of you who had not previously seen EWD.js in action, I hope that you can now understand its power and importance in the future of VistA.

I’ve deliberately released everything as Apache 2 Open Source products, and created this detailed series of articles to effectively remove all barriers to entry.  There is no longer any excuse for not evaluating, testing and ultimately using EWD.js to begin moving down the road to modernising VistA.  EWD.js will significantly speed development down that road, and make it both practical to do so and fun to do so.

EWD.js ticks all the boxes, meets all the requirements of both the Open Source development community and the VA and resolves all the issues that I’m aware of.  I’ve not seen any other viable solutions out there that are getting anywhere fast or delivering anything comparable.

Time, then, to start using EWD.js.  There are no longer any excuses.


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: