ewd-qoper8-vistarpc: exposing vista's rpcs as rest services
TRANSCRIPT
![Page 1: ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services](https://reader034.vdocument.in/reader034/viewer/2022051318/5a6617587f8b9a214f8b5359/html5/thumbnails/1.jpg)
Copyright © 2016 M/Gateway Developments Ltd
ewd-qoper8-vistarpc:Exposing VistA's RPCs as
REST services
Rob TweedDirector, M/Gateway Developments Ltd
Twitter: @rtweed
![Page 2: ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services](https://reader034.vdocument.in/reader034/viewer/2022051318/5a6617587f8b9a214f8b5359/html5/thumbnails/2.jpg)
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)
![Page 3: ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services](https://reader034.vdocument.in/reader034/viewer/2022051318/5a6617587f8b9a214f8b5359/html5/thumbnails/3.jpg)
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?
![Page 4: ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services](https://reader034.vdocument.in/reader034/viewer/2022051318/5a6617587f8b9a214f8b5359/html5/thumbnails/4.jpg)
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
![Page 5: ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services](https://reader034.vdocument.in/reader034/viewer/2022051318/5a6617587f8b9a214f8b5359/html5/thumbnails/5.jpg)
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
![Page 6: ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services](https://reader034.vdocument.in/reader034/viewer/2022051318/5a6617587f8b9a214f8b5359/html5/thumbnails/6.jpg)
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
![Page 7: ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services](https://reader034.vdocument.in/reader034/viewer/2022051318/5a6617587f8b9a214f8b5359/html5/thumbnails/7.jpg)
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
![Page 8: ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services](https://reader034.vdocument.in/reader034/viewer/2022051318/5a6617587f8b9a214f8b5359/html5/thumbnails/8.jpg)
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
![Page 9: ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services](https://reader034.vdocument.in/reader034/viewer/2022051318/5a6617587f8b9a214f8b5359/html5/thumbnails/9.jpg)
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
![Page 10: ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services](https://reader034.vdocument.in/reader034/viewer/2022051318/5a6617587f8b9a214f8b5359/html5/thumbnails/10.jpg)
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
![Page 11: ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services](https://reader034.vdocument.in/reader034/viewer/2022051318/5a6617587f8b9a214f8b5359/html5/thumbnails/11.jpg)
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
![Page 12: ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services](https://reader034.vdocument.in/reader034/viewer/2022051318/5a6617587f8b9a214f8b5359/html5/thumbnails/12.jpg)
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")
![Page 13: ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services](https://reader034.vdocument.in/reader034/viewer/2022051318/5a6617587f8b9a214f8b5359/html5/thumbnails/13.jpg)
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;
![Page 14: ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services](https://reader034.vdocument.in/reader034/viewer/2022051318/5a6617587f8b9a214f8b5359/html5/thumbnails/14.jpg)
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
});
![Page 15: ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services](https://reader034.vdocument.in/reader034/viewer/2022051318/5a6617587f8b9a214f8b5359/html5/thumbnails/15.jpg)
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());
![Page 16: ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services](https://reader034.vdocument.in/reader034/viewer/2022051318/5a6617587f8b9a214f8b5359/html5/thumbnails/16.jpg)
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' };
![Page 17: ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services](https://reader034.vdocument.in/reader034/viewer/2022051318/5a6617587f8b9a214f8b5359/html5/thumbnails/17.jpg)
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' };
![Page 18: ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services](https://reader034.vdocument.in/reader034/viewer/2022051318/5a6617587f8b9a214f8b5359/html5/thumbnails/18.jpg)
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
![Page 19: ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services](https://reader034.vdocument.in/reader034/viewer/2022051318/5a6617587f8b9a214f8b5359/html5/thumbnails/19.jpg)
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
![Page 20: ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services](https://reader034.vdocument.in/reader034/viewer/2022051318/5a6617587f8b9a214f8b5359/html5/thumbnails/20.jpg)
Copyright © 2016 M/Gateway Developments Ltd
Logging In
• For testing, use a REST client, eg:– Postman– Chrome Advanced REST Client
![Page 21: ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services](https://reader034.vdocument.in/reader034/viewer/2022051318/5a6617587f8b9a214f8b5359/html5/thumbnails/21.jpg)
Copyright © 2016 M/Gateway Developments Ltd
Logging InEnter the URL: /vista/login
![Page 22: ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services](https://reader034.vdocument.in/reader034/viewer/2022051318/5a6617587f8b9a214f8b5359/html5/thumbnails/22.jpg)
Copyright © 2016 M/Gateway Developments Ltd
Logging InEnter the URL: /vista/login
Must be a POST
![Page 23: ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services](https://reader034.vdocument.in/reader034/viewer/2022051318/5a6617587f8b9a214f8b5359/html5/thumbnails/23.jpg)
Copyright © 2016 M/Gateway Developments Ltd
Logging InEnter the URL: /vista/login
Must be a POST
Note the content-type
![Page 24: ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services](https://reader034.vdocument.in/reader034/viewer/2022051318/5a6617587f8b9a214f8b5359/html5/thumbnails/24.jpg)
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
![Page 25: ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services](https://reader034.vdocument.in/reader034/viewer/2022051318/5a6617587f8b9a214f8b5359/html5/thumbnails/25.jpg)
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!
![Page 26: ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services](https://reader034.vdocument.in/reader034/viewer/2022051318/5a6617587f8b9a214f8b5359/html5/thumbnails/26.jpg)
Copyright © 2016 M/Gateway Developments Ltd
Logging In
Copy this token:
![Page 27: ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services](https://reader034.vdocument.in/reader034/viewer/2022051318/5a6617587f8b9a214f8b5359/html5/thumbnails/27.jpg)
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
![Page 28: ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services](https://reader034.vdocument.in/reader034/viewer/2022051318/5a6617587f8b9a214f8b5359/html5/thumbnails/28.jpg)
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
![Page 29: ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services](https://reader034.vdocument.in/reader034/viewer/2022051318/5a6617587f8b9a214f8b5359/html5/thumbnails/29.jpg)
Copyright © 2016 M/Gateway Developments Ltd
Try it
Enter the escaped URL: /vista/runRPC/…
![Page 30: ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services](https://reader034.vdocument.in/reader034/viewer/2022051318/5a6617587f8b9a214f8b5359/html5/thumbnails/30.jpg)
Copyright © 2016 M/Gateway Developments Ltd
Try it
Enter the escaped URL: /vista/runRPC/…
Must be a POST
![Page 31: ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services](https://reader034.vdocument.in/reader034/viewer/2022051318/5a6617587f8b9a214f8b5359/html5/thumbnails/31.jpg)
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
![Page 32: ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services](https://reader034.vdocument.in/reader034/viewer/2022051318/5a6617587f8b9a214f8b5359/html5/thumbnails/32.jpg)
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
![Page 33: ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services](https://reader034.vdocument.in/reader034/viewer/2022051318/5a6617587f8b9a214f8b5359/html5/thumbnails/33.jpg)
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
![Page 34: ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services](https://reader034.vdocument.in/reader034/viewer/2022051318/5a6617587f8b9a214f8b5359/html5/thumbnails/34.jpg)
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
![Page 35: ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services](https://reader034.vdocument.in/reader034/viewer/2022051318/5a6617587f8b9a214f8b5359/html5/thumbnails/35.jpg)
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
![Page 36: ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services](https://reader034.vdocument.in/reader034/viewer/2022051318/5a6617587f8b9a214f8b5359/html5/thumbnails/36.jpg)
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
![Page 37: ewd-qoper8-vistarpc: Exposing VistA's RPCs as REST Services](https://reader034.vdocument.in/reader034/viewer/2022051318/5a6617587f8b9a214f8b5359/html5/thumbnails/37.jpg)
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