My three previous posts have provided an overview of openMDWS, technical details on how to define openMDWS services and how to install openMDWS.
In this article I’ll be looking at how you can very simply test openMDWS methods that have been wrappered to behave as an HTTP/XML-based web service.
The current implementation of openMDWS provides a simple HTTP GET interface. I have plans to extend the Node.js-based gateway module for EWD (ewdGateway.js) to provide a full VA MDWS-compatible request interface. For now, the interface you use for any registered openMDWS method is a simple HTTP GET request:
http://[domainName]/[ewdPath]/openMDWS/get.ewd?facade=[facadeName]&method=[methodName][&name=value]... where: - domainName = the domain name or IP address of the web server providing the front end to the VistA system whose openMDWS service you want to consume - ewdPath = the path on the VistA system that is configured for EWD (usually either /ewd/ or /vista/. dEWDrop servers use /vista/ by default) - facadeName = the name of the openMDWS facade containing the openMDWS service you require - method = the name of the openMDWS operation you wish to invoke within the specified facade - [&name=value] denotes the list of additional name/value pairs needed by the specified openMDWS operation eg: http://example.com/vista/openMDWS/get.ewd?facade=EmrSvc& method=connect&sitelist=smart2
Accessing a VistA system via openMDWS always requires the invocation of two initial operations that are already built-in to openMDWS:
– connect: this behaves identically to the MDWS connect operation, but in openMDWS, it establishes initial contact with the VistA server, initiates an EWD session and adds an EWD security token to the MDWS connect XML response;
– login: this behaves identically to the MDWS login operation. It validates the accessCode and verifyCode that is specified in the request. The user’s DUZ value is returned in the XML response, and is also automatically added to the EWD Session.
openMDWS uses an identical session cookie as standard MDWS, but the openMDWS session cookie contains within it the EWD token that was generated by the initial connect operation. Subsequent requests to openMDWS should therefore always include this cookie which ensures that the openMDWS EWD back-end will securely re-establish connection to the original EWD Session. This prevents unauthorised access to openMDWS operations. By using an identical cookie structure/syntax, openMDWS services will be capable of being consumed by existing applications that have been built around VA MDWS.
Once you’ve installed openMDWS you can immediately try these two pre-built methods out. If you’re using a dEWDrop server, the default accessCode and verifyCode are worldvista6 and $#happy7 respectively. For example, suppose your dEWDrop server is running on IP address 192.168.1.120. You can run the connect operation by entering the following into a browser:
Note that HTTP access is blocked by default on dEWDrop servers, so you must specify https:// at the start of the URL. When you first invoke the URL, you’ll get a warning about the SSL certificate: just accept this as it’s simply warning you that the dEWDrop server uses self-certified SSL credentials rather than a proper SSL certificate.
You should get the following response:
<DataSourceArray xmlns="http://mdws.medora.va.gov/EmrSvc" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <items> <DataSourceTO> <context/> <description/> <ewdToken>SaDZBgvpF8AvwARDJUe4stPsGgIKs6</ewdToken> <modality>HIS</modality> <port>9100</port> <protocol>VISTA</protocol> <provider>127.0.0.1</provider> <siteId> <tag>dewdrop</tag> <text>dEWDrop</text> </siteId> <status>active</status> <testSource>false</testSource> <timeout>0</timeout> <vendor/> <version/> <welcomeMessage> WorldVistA EHR /VOE 1.0 ...etc </welcomeMessage> </DataSourceTO> </items> </DataSourceArray>
Then try running the login operation:
Note that the verifyCode must be URL escaped, so the # character must be replaced with %23.
The example above conforms with the pukka MDWS login operation which specifies that the accessCode and verifyCode are specified using the name/value pairs username and pwd respectively. openMDWS allows you to use the more intuitive names in the URL, eg:
Using either of the two URLs above, you should get a successful login response as follows:
<UserTO xmlns="http://mdws.medora.va.gov/EmrSvc" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <DUZ>77</DUZ> <SSN/> <greeting>Good morning DOCTOR,YOURNAME</greeting> <name>DOCTOR,YOURNAME</name> <siteId/> </UserTO>
You have successfully logged into the VistA system on the dEWDrop server via openMDWS!
If you’ve used Chrome as your browser, you can use the built-in Developer Tools to view the request and response headers that were sent and received. You should see a MDWS-compatible cookie containing an EWD token, eg:
This cookie was initially generated by the response created for the connect operation by openMDWS.
Note: if you run consecutive connect requests, you may find that login requests begin returning a fault:
<DataSourceArray xmlns="http://mdws.medora.va.gov/EmrSvc" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <count>0</count> <fault> <message> There is no connection to log onto: cookie missing or invalid </message> <stackTrace/> <suggestion/> <type/> </fault> </DataSourceArray>
If you see this in your browser, you’ll probably have to clear cookies from your browser’s cache and re-run the connect service to generate a fresh MDWS cookie.
When you create your own openMDWS services and register them, you can immediately test them out in the same way by using a browser (note that you’ll need to invoke the connect and login methods first). Just substitute the facade and method names in the URL with the ones you used to register your method, and add any inputs required by your method via additional name/value pairs to the end of the URL.
You can probably see that you are now ready to begin using openMDWS services from within any programming/application development environment that supports HTTP/XML-based web services.
However, if you’re developing web and mobile applications on top of VistA, EWD really comes into its own and is the fastest way of building web applications for VistA. EWD knows all about openMDWS and makes the use of openMDWS services almost trivially simple. So, in the next posting I’ll look at how openMDWS services can be consumed within EWD.