Upload
rob-tweed
View
118
Download
1
Embed Size (px)
Citation preview
Copyright © 2016 M/Gateway Developments Ltd
ewd-qoper8-vistarpc:Exposing VistA's RPCs as
REST services
Rob TweedDirector, 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-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
Copyright © 2016 M/Gateway Developments Ltd
Installing ewd-qoper8-vistarpcCopy:
C:\ewd3\node_modules\ewd-qoper8-vistarpc\example\ewd-vista-express.js
To:
C:\ewd3\ewd-vista-express.js
Copyright © 2016 M/Gateway Developments Ltd
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
Copyright © 2016 M/Gateway Developments Ltd
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")
Copyright © 2016 M/Gateway Developments Ltd
Configure ewd-qoper8-vistarpcIf you want it to listen on a port other than 8080, edit
C:\ewd3\ewd-vista-express.js
Line 69:
var port = 8080;
Copyright © 2016 M/Gateway Developments Ltd
Configure ewd-qoper8-vistarpcIf you want more than 1 ewd-qoper8 worker process, edit
C:\ewd3\ewd-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-vistarpcIf you want it to use a URL prefix other than /vista, edit
C:\ewd3\ewd-vista-express.js
Line 61:
app.use('/vista', qx.router());
Copyright © 2016 M/Gateway Developments Ltd
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' };
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, editappropriately, eg:
var params = { path: 'C:\\InterSystems\\Cache2015-2\\mgr', namespace: 'GOLD', username: 'CacheUser', password: 'secret1234' };
Copyright © 2016 M/Gateway Developments Ltd
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
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 InEnter the URL: /vista/login
Copyright © 2016 M/Gateway Developments Ltd
Logging InEnter the URL: /vista/login
Must be a POST
Copyright © 2016 M/Gateway Developments Ltd
Logging InEnter the URL: /vista/login
Must be a POST
Note the content-type
Copyright © 2016 M/Gateway Developments Ltd
Logging InEnter 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 InEnter 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 forAuthorization header
Must be a POST
Copyright © 2016 M/Gateway Developments Ltd
Try it
Enter the escaped URL: /vista/runRPC/…
Valid token used as value forAuthorization header
JSON payload appropriatefor the content needed forthe 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 forAuthorization header
JSON payload appropriatefor the content needed forthe specified RPC
Must be a POST
Successful response
JSON content depends onRPC
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