Testing openMDWS Services

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:

https://192.168.1.120/vista/openMDWS/get.ewd?method=connect&
facade=EmrSvc&sitelist=dewdrop

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:

https://192.168.1.120/vista/openMDWS/get.ewd?method=login&
facade=EmrSvc&username=worldvista6&pwd=$%23happy7

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:

https://192.168.1.120/vista/openMDWS/get.ewd?method=login&
facade=EmrSvc&accessCode=worldvista6&verifyCode=$%23happy7

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:

Cookie:ASP.NET_SessionId=4tRN9jereXKGPDadLpJFcdGU70dLGu

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.

 

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: