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 TweedDirector, 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-vistarpccd \ewd3npm install express body-parser npm install ewd-qoper8 ewd-qoper8-express ewd-qoper8-cachenpm install ewd-session ewd-qoper8-vistarpc

Note: check first in C:\ewd3\node_modulesIf 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


Installing ewd-qoper8-vistarpcCopy:

C:\ewd3\node_modules\ewd-qoper8-vistarpc\example\ewd-vista-express.js

To:

C:\ewd3\ewd-vista-express.js


Installing ewd-qoper8-vistarpcCopy:

C:\ewd3\node_modules\ewd-qoper8-vistarpc\example\vista-worker-module.js

To:

C:\ewd3\node_modules\vista-worker-module.js


Installing ewd-qoper8-vistarpcInstall the Mumps code that maintains the Mumps symbol table for VistA

- Start a Cache Terminal process

w $system.OBJ.Load("C:\ewd3\node_modules\ewd-session\mumps\ewdSymbolTable.xml","ck")

Install the Mumps wrapper function that interfaces VistA's RPCs

- In the same Cache Terminal process

w $system.OBJ.Load("C:\ewd3\node_modules\ewd-qoper8-vistarpc\mumps\ewdVistARPC.xml","ck")


Configure ewd-qoper8-vistarpcIf you want it to listen on a port other than 8080, edit


Line 69:

var port = 8080;


Configure ewd-qoper8-vistarpcIf 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

});


Configure ewd-qoper8-vistarpcIf you want it to use a URL prefix other than /vista, edit


Line 61:

app.use('/vista', qx.router());


Configure ewd-qoper8-vistarpcCheck:

C:\ewd3\node_modules\vista-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:\\InterSystems\\Cache2015-2\\mgr', namespace: 'GOLD' };


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, editappropriately, eg:

var params = { path: 'C:\\InterSystems\\Cache2015-2\\mgr', namespace: 'GOLD', username: 'CacheUser', password: 'secret1234' };


Start ewd-qoper8-vistarpccd \ewd3node 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 InEnter the URL: /vista/login



Must be a POST



Must be a POST

Note the content-type



Must be a POST

Enter the Access Code &Verify Code as a JSON payload




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 forAuthorization header

Must be a POST


Try it



JSON payload appropriatefor the content needed forthe specified RPC

Must be a POST


Try it



JSON payload appropriatefor the content needed forthe specified RPC

Must be a POST

Successful response

JSON content depends onRPC


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

Software

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