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

Copyright © 2016 M/Gateway Developments Ltd
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)

Copyright © 2016 M/Gateway Developments Ltd
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?

Copyright © 2016 M/Gateway Developments Ltd
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

Copyright © 2016 M/Gateway Developments Ltd
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

Copyright © 2016 M/Gateway Developments Ltd
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

Copyright © 2016 M/Gateway Developments Ltd
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

Copyright © 2016 M/Gateway Developments Ltd
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

Copyright © 2016 M/Gateway Developments Ltd
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

Copyright © 2016 M/Gateway Developments Ltd
Installing ewd-qoper8-vistarpc
Copy:
C:ewd3node_modulesewd-qoper8-vistarpcexampleewd-vista-express.js
To:
C:ewd3ewd-vista-express.js

Copyright © 2016 M/Gateway Developments Ltd
Installing ewd-qoper8-vistarpc
Copy:
C:ewd3node_modulesewd-qoper8-vistarpcexamplevista-worker-module.js
To:
C:ewd3node_modulesvista-worker-module.js

Copyright © 2016 M/Gateway Developments Ltd
Installing ewd-qoper8-vistarpc
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")

Copyright © 2016 M/Gateway Developments Ltd
Configure ewd-qoper8-vistarpc
If you want it to listen on a port other than 8080, edit
C:ewd3ewd-vista-express.js
Line 69:
var port = 8080;

Copyright © 2016 M/Gateway Developments Ltd
Configure ewd-qoper8-vistarpc
If you want more than 1 ewd-qoper8 worker process, edit
C:ewd3ewd-vista-express.js
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
});

Copyright © 2016 M/Gateway Developments Ltd
Configure ewd-qoper8-vistarpc
If you want it to use a URL prefix other than /vista, edit
C:ewd3ewd-vista-express.js
Line 61:
app.use('/vista', qx.router());

Copyright © 2016 M/Gateway Developments Ltd
Configure ewd-qoper8-vistarpc
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'
};

Copyright © 2016 M/Gateway Developments Ltd
Configure ewd-qoper8-vistarpc
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'
};

Copyright © 2016 M/Gateway Developments Ltd
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

Copyright © 2016 M/Gateway Developments Ltd
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

Copyright © 2016 M/Gateway Developments Ltd
Logging In
• For testing, use a REST client, eg:
– Postman
– Chrome Advanced REST Client

Copyright © 2016 M/Gateway Developments Ltd
Logging In
Enter the URL: /vista/login

Copyright © 2016 M/Gateway Developments Ltd
Logging In
Enter the URL: /vista/login
Must be a POST

Copyright © 2016 M/Gateway Developments Ltd
Logging In
Enter the URL: /vista/login
Must be a POST
Note the content-type

Copyright © 2016 M/Gateway Developments Ltd
Logging In
Enter the URL: /vista/login
Must be a POST
Enter the Access Code &
Verify Code as a JSON payload
Note the content-type

Copyright © 2016 M/Gateway Developments Ltd
Logging In
Enter the URL: /vista/login
Must be a POST
Enter the Access Code &
Verify Code as a JSON payload
Note the content-type
Success!

Copyright © 2016 M/Gateway Developments Ltd
Logging In
Copy this token:

Copyright © 2016 M/Gateway Developments Ltd
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

Copyright © 2016 M/Gateway Developments Ltd
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

Copyright © 2016 M/Gateway Developments Ltd
Try it
Enter the escaped URL: /vista/runRPC/…

Copyright © 2016 M/Gateway Developments Ltd
Try it
Enter the escaped URL: /vista/runRPC/…
Must be a POST

Copyright © 2016 M/Gateway Developments Ltd
Try it
Enter the escaped URL: /vista/runRPC/…
Valid token used as value for
Authorization header
Must be a POST

Copyright © 2016 M/Gateway Developments Ltd
Try it
Enter the escaped URL: /vista/runRPC/…
Valid token used as value for
Authorization header
JSON payload appropriate
for the content needed for
the specified RPC
Must be a POST

Copyright © 2016 M/Gateway Developments Ltd
Try it
Enter the escaped URL: /vista/runRPC/…
Valid token used as value for
Authorization header
JSON payload appropriate
for the content needed for
the specified RPC
Must be a POST
Successful response
JSON content depends on
RPC

Copyright © 2016 M/Gateway Developments Ltd
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

Copyright © 2016 M/Gateway Developments Ltd
Symbol Table Maintenance
• 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

Copyright © 2016 M/Gateway Developments Ltd
Symbol Table Maintenance
• 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

Copyright © 2016 M/Gateway Developments Ltd
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