Releasing vistarpc4r gem

Our new gem, vistarpc4r, is finally ready for other people to play with. It's pretty bare-bones, but it works.

vistarpc4r is a Ruby gem that provides RPC-style API calls to any of the VistA-variant servers that support the RPCBroker(of which they all do, unless disabled). VistA is the Veteran's Adminstration electronic health record system that it released to the public. We have tested vistarpc4r on Medsphere's OpenVista, but it should work on WorldVistA, vxVistA, and the others.

We developed this gem to support our own work developing our new product CompleteNote, which is a clinical decision support and documentation application.

This gem is free to download and use.

Feel free to bug me about additional functionality you would like to see, or contributions you would like to make.

The gem is available through rubygems.org: https://rubygems.org/gems/vistarpc4r

Installation
$ gem install vistarpc4r

Usage
VistA is an old-school stateful session server. It follows the standard RPC model of creating a tcp connection to a server, providing user credentials, and then calling named RPC functions with arguments, and receiving status and data responses in a synchronous manner.

vistarpc4r provides a ruby class called RPCBrokerConnection.
RPCBrokerConnection has 6 primary methods:

• new(server, port, userid, password, debug) - string server, number port, string userid and password, and true or false to turn on debug statements(default = false)
  
• connect - initiate the connection(addresses and usernames are passed in at object creation)
• setContext('context') - In VistA, function calls are controlled by assigning them to contexts and giving the user access to that context. In most cases the desired context is 'OR CPRS GUI CHART'. There is a logical reason for that, but I won't get into it right now.
• close - It wouldn't be a good RPC connection library without a close method
• call_s('rpcname', [Ruby Array of arguments]) - Call a VistA RPC function with an array of arguments, expecting a single string value in return.
• call_a('rpcname', [Ruby Array of arguments]) - Call a VistA RPC function with an array of arguments, expecting a Ruby Array of return values.
  

So, now what? What are the RPC functions I can call? That is the eternal question when it comes to VistA. There are hundreds, if not thousands, of RPC functions. While the VA decided to release VistA to the public, it didn't come with great documentation, or I should say, the source code is the documentation. Medsphere.org, hardhats.org and the VA site all offer clues.

I will publish my findings for good RPC functions as I am cruising the source code myself. The source code that offers the best insight is written in Delphi, MUMPS, Java and C#.

Example
Fortunately, Medsphere has created a public demo Openvista server that is always available(and resets its content in the middle of the night) Information about it is available here --> https://medsphere.org/docs/DOC-1003

But lets try this out...

Fire up irb or script/console or whatever your preference is...

broker = VistaRPC4r::RPCBrokerConnection.new('openvista.medsphere.org', 9201, 'PU1234', 'PU1234!!')
broker.connect
broker.setContext('OR CPRS GUI CHART')
wardsarray = broker.call_a("ORQPT WARDS")
wardsarray.each do |ward|
a = ward.split("^")
puts "Ward:" + a[1]
wardarray = broker.call_a("ORQPT WARD PATIENTS", [a[0]]) # ward ien
wardarray.each do |patient|
b = patient.split("^")
puts b[0] + ":" + b[1]
end
end

This example displays a list of wards and the names and internal ids of patients on those wards.
^ is used as a sort of field separator when multiple values are returned in the same string.

I have code in the examples directory in this gem that will give you other examples of fetching other data as well as writing and deleting data on the server.

Future features

• Ruby classes for VistA data objects. Patients, Providers, Problems, Vitals, Orders, etc....
• ActiveRecord interface for VistA. Won't be easy but seems doable from what I've seen.
• Connection management. An obvious thing for us Railers is to incorporate VistA into a web application(I didn't need it yet). Given the stateful server and authentication model it isn't straightforward, but certainly doable.

Enjoy. Updates as I make progess.