ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services

Copyright © 2016 M/Gateway Developments Ltd
ewd-qoper8-vistarpc:
Exposing VistA's RPCs as
REST services
Rob Tweed
Director, M/Gateway Developments Ltd
Twitter: @rtweed

VistA?
• The US Dept of Veterans' Affairs (VA)
Electronic Healthcare Register (EHR)
• Legacy Mumps application
– Huge application
– Highly functional and well-regarded
– But: Millions of lines of terse Mumps code
– But: Old-fashioned user interfaces
• Roll & scroll / "green screen" / "dumb terminal"
• Delphi (CPRS)

VistA Modernisation using EWD 3
• EWD 3 offers great opportunities for
modernising VistA
– New user interfaces
• Browser-based
• Mobile (using React Native)
• Electron (desktop)
– Exposing VistA as a set of REST-ful services?

Key problems
• VistA was designed as a stateful
application:
– Directly-connected terminal providing the user
interface
– Mumps/Caché process maintains state via
"local variables" to which the user's process
has continual, direct access

Key problems
• EWD 3 is stateless
– Executes application code in discrete,
independent chunks
– Different physical Mumps/Caché processes
may handle each successive request from
browser
– EWD 3 provides its own state maintenance
mechanism
• But this is nothing to do with Mumps local variables

VistA RPCs
• VistA provides a mechanism for defining chunks
of pre-defined behaviour
– Known as RPCs
– Designed for use with CPRS (Delphi)
• Many RPCs already exist
– Many are well known and understood by VistA/CPRS
developers
– However, they vary in quality and level of
conformance to the expected pattern(s) for RPCs

Alternatives to RPCs
• FileMan APIs
– FileMan is VistA's integrated data dictionary
– Access to VistA's data should always be via
FileMan
• RPCs are supposed to do this

ewd-qoper8-vistarpc
• A pre-built EWD 3-based platform for
exposing VistA's RPCs as REST services
– Provides a solution for accessing VistA's
stateful environment as a set of stateless
requests
• Performs a trick whereby the Mumps local
variables (aka "symbol table") is maintained in an
EWD Session
– JSON input to RPCs
– JSON output from RPCs

Installing ewd-qoper8-vistarpc
cd ewd3
npm install express body-parser
npm install ewd-qoper8 ewd-qoper8-express ewd-qoper8-cache
npm install ewd-session ewd-qoper8-vistarpc
Note: check first in C:ewd3node_modules
If you've been running all the examples in previous parts of this course,
You'll already have installed most of these modules
You may only need to do this:
npm install ewd-qoper8-vistarpc

Copy:
C:ewd3node_modulesewd-qoper8-vistarpcexampleewd-vista-express.js
To:
C:ewd3ewd-vista-express.js

Copy:
C:ewd3node_modulesewd-qoper8-vistarpcexamplevista-worker-module.js
To:
C:ewd3node_modulesvista-worker-module.js

Install the Mumps code that maintains the Mumps symbol table for VistA
- Start a Cache Terminal process
w $system.OBJ.Load("C:ewd3node_modulesewd-sessionmumpsewdSymbolTable.xml","ck")
Install the Mumps wrapper function that interfaces VistA's RPCs
- In the same Cache Terminal process
w $system.OBJ.Load("C:ewd3node_modulesewd-qoper8-vistarpcmumpsewdVistARPC.xml","ck")

Configure ewd-qoper8-vistarpc
If you want it to listen on a port other than 8080, edit
Line 69:
var port = 8080;

If you want more than 1 ewd-qoper8 worker process, edit
Add after this line (line 70):
app.listen(port);
q.on('start', function() {
this.setWorkerPoolSize(3); // 3 workers or change to however many you need
});

If you want it to use a URL prefix other than /vista, edit
Line 61:
app.use('/vista', qx.router());

Check:
C:ewd3node_modulesvista-worker-module.js
The Cache configuration is defined at about line 58:
var connectCacheTo = require('ewd-qoper8-cache');
var params = {
namespace: 'VISTA'
};
Change the namespace and path if required, eg
var params = {
path: 'C:InterSystemsCache2015-2mgr',
namespace: 'GOLD'
};

Some systems may use a different username & password for Caché also
Defaults are _SYSTEM and SYS respectively. If yours are different, edit
appropriately, eg:
var params = {
path: 'C:InterSystemsCache2015-2mgr',
namespace: 'GOLD',
username: 'CacheUser',
password: 'secret1234'
};

Start ewd-qoper8-vistarpc
cd ewd3
node ewd-vista-express
Worker Bootstrap Module file written to node_modules/ewd-qoper8-worker.js
========================================================
ewd-qoper8 is up and running. Max worker pool size: 1
========================================================
ewd-qoper8-vistarpc is now running and listening on port 8080

ewd-qoper8-vistarpc APIs
• There are really only two:
– login
• Authenticates the user via his/her Access Code &
Verify Code
• Returns a security / EWD Session token
– runRPC
• Executes the specified RPC
• Request must be authenticated using a valid token

Logging In
• For testing, use a REST client, eg:
– Postman
– Chrome Advanced REST Client

Logging In
Enter the URL: /vista/login

Logging In
Must be a POST

Logging In
Must be a POST
Note the content-type

Logging In
Must be a POST
Enter the Access Code &
Verify Code as a JSON payload

Logging In
Must be a POST
Enter the Access Code &
Verify Code as a JSON payload
Success!

Logging In
Copy this token:

runRPC
• Now that you're logged in, you can
invoked any RPC that your Access Code
is allowed to use. The URL is:
POST http://192.168.1.100:8080/vista/runRPC/[RPC Name]
For example
POST http://192.168.1.100:8080/vista/runRPC/DDR GETS ENTRY DATA
Note you may need to URL-escape the URL:
POST http://192.168.1.100:8080/vista/runRPC/DDR%20GETS%20ENTRY%20DATA

runRPC
• runRPC POST requests must be
authenticated using the Session Token
returned by a successful /login request
• The token value is used in the
Authorization header

Try it
Enter the escaped URL: /vista/runRPC/…

Try it
Must be a POST

Try it
Valid token used as value for
Must be a POST

Try it
JSON payload appropriate
for the content needed for
the specified RPC
Must be a POST

Try it
JSON payload appropriate
for the content needed for
the specified RPC
Must be a POST
Successful response
JSON content depends on
RPC

Symbol Table Maintenance
• After successful /login, the Mumps symbol
table is saved to the user's Session
– Uses a special undocumented Caché
function:
• $zu(160)
• Very high-speed symbol-table copy to/from a
global (in this case the user's Session global)
– The user's DUZ etc is therefore captured

• When a runRPC request is received:
– Token in Authorization header is checked
– If valid, it now knows the user's Session
– Symbol table is restored into Caché process
• On completion of runRPC, after response
returned to client:
– Symbol table is saved back to user's Session

• RPC is therefore invoked in user's correct
run-time MUMPS context
– DUZ etc is correct for each RPC invoked by a
user
• Even though RPCs are being invoked
statelessly by potentially different Caché
processes each time, they appear to be
running in a stateful environment

Ongoing Development
• Some functionality isn't necessarily
correct, eg:
– Handling contexts
• ewdVistARPC Mumps routine needs peer
review and discussion
– eg Sam Habiel and Nikolay Topalov already
discussing its finer details
– Use the EWD Google group for such
discussions

ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services

Similar to ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services (20)

More from Rob Tweed

More from Rob Tweed (12)

Recently uploaded

Recently uploaded (20)

ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services