vistarpc4r Tutorial 3: Lists (part one)

So now we have a running system, we can configure some basic elements, and we can add providers and patients.  What's next?
Well, VistA has a ton of data already loaded for you, so let's check it out.

Most things(objects) in VistA have an internal and external representation.  Basically this means each object has an internal id and a value.  The internal id is generally a positive integer(often referred to as an IEN or IFN or DFN).  The value is generally a human readable string.
Lists are returned as an array of string.
Here are the first bunch with Ruby code:

Providers

array = broker.call_a("ORQPT PROVIDERS")
puts array[0]  # outputs providerIEN^providername  e.g. 42^ USER,PHYSICIAN

Locations
Clinics - Outpatient

array = broker.call_a("ORWU CLINCLOC", ["", "1"])
puts array[0]  # outputs locationIEN^locationname e.g. 15^CARDIOLOGY

Wards - Inpatient

array = broker.call_a("ORQPT WARDS")
puts array[0] # outputs locationIEN^locationname e.g. 2^MED/SURG

Patients - There are many ways to get lists of patients.  Some examples:
By Ward

array = broker.call_a("ORQPT WARD PATIENTS", [wardIEN])
puts array[0] # outputs patientIEN^patientname  e.g. 17^SMITH,BETTY

All Patients

array = broker.call_a("ORWPT LIST ALL", ["", "1"])

This call returns a preset number of patients out of the list.  You need to use this call in a loop where you call the RPC additional times using the last array entry from the previous call as the first argument until it returns an array of size 0.

You can also get lists of patient by provider, appointment dates, teams, and others.  Let me know if you need help finding the RPCs

Problems
Problems use a search approach.

array = broker.call_a("ORQQPL PROBLEM LEX SEARCH", ["hypertension", "100", "", "0"])

Argument 1 is the term you are looking for
Argument 2 is the maximum number of matches
Argument 3 is something to do with view...leaving it blank
Argument 4 is the date to use for determining when problems were valid in the VistA system.

puts array[0]  # problemIEN^problemname^codename^codeIEN^code source
# for example:  60339^Hypertension *^401.9^2477^ICD-9-CM

Up next...medication lists, procedure lists, and other order lists.

vistarpc4r Tutorial 2: Users, Locations, Patients, Dates

This second tutorial continues where we left off in tutorial #1, and assumes you have an OpenVistA system setup on Ubuntu.  

Many of the VistA RPC calls you can make though vistarpc4r require either a patient, provider, location or date.  In some cases, all of them.  Most VistA flavors come with some sample patients, providers or locations, but if you are developing software to work with VistA, you probably need to create some of your own.  

However.....standard VistA does not include a RPC to create ANY of them.  There are a variety of reasons, many non-technical ones regarding politics surrounding Federal software development can be read at the Hardhats google group.  I prefer to think it is because the actual users of CPRS aren't the ones creating the patients, and user accounts, so no need, no build.  

But....I have at least one work around.

So first, users, or usually referred to as providers.

User creation

For user creation, it's terminal time(although I believe Astronaut has a user config tool)

I need super providers for my development sandbox.  By that I mean, they have the ability to do just about everything in the VistA GUI.  For me that means a provider that can sign orders containing narcotics.  

I prefer Fileman to create users so:

$ openvista open

OPEN> D P^DI               # start Fileman

Login as man,sys

Select Option 1:  Add/Edit Entries

Select the NEW PERSON file

Edit All Fields                   # which is painful, but you won't miss anything

Select NEW PERSON NAME  - type in your new users name in LAST,FIRST format

You will then start going through fields.  ? and ?? give good answers as to what is expected.  

But some key fields:

ACCESS:  basically your login name

VERIFY:   a password

KEYS:  PROVIDER, ORES    # these are necessary to sign orders

SECONDARY MENU OPTIONS:  OR CPRS GUI CHART

PRIMARY MENU OPTION:  RGWBMAIN

CPRS TAB: RPT
CPRS TAB: COR

AUTHORIZED TO WRITE MED ORDERS:  YES

DEA: 2 letters, followed by 7 numbers, but there is an algorithm

ELECTRONIC SIGNATURE CODE:  A string the user types in to verify its them.  like JSMITH

Once you create one, you can clone it!

Go into EVE, which is D ^ZU, instead of D P^DI

Select User management

Select Grant access by profile 

Use your existing user as a template, and create new users!
Don't forget to change for each user: Access, verify, DEA, Signature

Add Locations(no RPC for this either)

Adding a location is a similiar experience to adding your first user. In this case edit file 44, the location file. Fill out what makes sense. Again ? and ?? will show you fairly good help.

Add Patients

So I have a RPC for this, but I don't feel good about. VistA does not come with one out of the box, but the Astronaut folks have created one. For my purposes, I needed to be able to add a lot of patients in bulk(but very few providers and locations). So I jammed the Astronaut modification into my plain vanilla OpenVista.

KIDS is the name of VistA's patching capability. People can bundle up their code changes as KIDS builds and distribute them for people to patch their system. In this case, I grabbed the KIDS build out of the Astronaut source tree installed it.

Grab kids.ov.tar.gz from

http://bazaar.launchpad.net/~ivaldes-hal-pc/astronaut-vista-server/trunk/files/head:/astro-distro/openvista

From that archive, we need the 0.8-2/TMG1-1.0-2d.KIDS file. Make sure it is on the OpenVistA server.

From the archive, I followed the commands in the file 0.8-2/TMG1-1.0-2d.TOY.sh

First we load the new code into the instance:

$ openvista open

OPEN> S DUZ=1,DUZ(0)="@"

OPEN> D ^XPDIL

# enter the path and filename for the KIDS file

# answer YES

OPEN>  h  # to halt

Then we install the code so that it runs and is available

$ openvista open

OPEN> S DUZ=1,DUZ(0)="@"

OPEN> D ^XPDI

TMG1*1.0*2

NO

NO

OPEN> h

During this installation process, you WILL GET ERRORS.  Wierd, nasty looking errors.  That is the part I don't feel good about.  But the add patient RPC works!!!!  

To use:

broker.call_s("TMG ADD PATIENT", [ [ 

    ["\"COMBINED NAME\"", "Test,Patient"],

    ["\"DOB\"", "12/1/68"],

    ["\"SEX\"", "M"],

    ["\"SS_NUM\"", "000000000"]

    ]]

The RPC returns the DFN, or internal identifier(which is an integer), for this new patient. 

For bulk loading, our experience is that the RPC breaks after a number of consecutive calls.  It looks like a timing bug.  Surrounding the call with the usual BEGIN/RESCUE/END, and resetting the connection works. 

Fileman Dates

Lastly, most of the RPCs that require dates for their arguments need them in Fileman format. Fileman format means take your usual YYYYMMDD.HHMMSS format and subtract 17000000.  For example, 20110911.090123 would be entered as 3110911.090123

Well, that gives you some basic infrastructure.  Enjoy.

Up next will be reviewing some specific RPCs that give you lists of stuff.

vistarpc4r Tutorial 1: Setting up an OpenVistA instance and database sandbox

This is a tutorial to help you set up a Medsphere OpenVistA system that you can use to play with vistarpc4r, our gem that provides Ruby access to VistA.  It is a pretty barebones setup, just enough for our own product development.  

For our needs, we decided to rely on Amazon Web Services' EC2 stuff.  

1.  Create Amazon EC2 instance. We used AMI ami-ccf405a5, which is an plain vanilla Ubuntu install, but for Maverick Meerkat, since that seems to be the latest version of Ubuntu that Medsphere supports. You get a default user 'ubuntu'

2. Update APT and download the OpenVistA package - Follow the instructions at https://medsphere.org/docs/DOC-1722.

3. Add the user 'ubuntu' to the gtm and openvista groups

1. $sudo adduser ubuntu gtm
2. $sudo adduser ubuntu openvista

4. More or less follow the instructions from https://medsphere.org/docs/DOC-1511

1. $ sudo ovinstanceadd open               # creates an OpenVistA instance in GT.M
2. Download the OpenVistA MUMPS code and globals.  This is the code, written in MUMPS, that is VistA.  The globals are the initial data to populate the database, like ICD-9 codes, medications lists, and some sample patients and providers.  Get the code from https://medsphere.org/download/project/openvista-server
3. Unzip the files you get from Medsphere(may need to install unzip with APT)
4. sudo ovimport -r <directory containing routines> -g <directory>globals.zwr open # loads the code and data into your OpenVistA instance
5. /opt should now contain some directories that have all of the code and globals

5. $openvista open # Fires up your instance

6. OPEN> D P^DI # Fires up Fileman, log in as man,sys

7. When you are done having fun with Fileman, enter "h" at the OPEN> prompt to halt back to the shell

8. $ /etc/init.d/openvista start             # start up the RPC Broker

Now you have a working instance of OpenVista.  You can point the CPRS or CIS GUI at this instance and see the sample data that Medsphere has loaded for you. 


Or, of course, you can point vistarpc4r at it!!!!!!

Next:  Tutorial 2:  How do you add users and patients with vistarpc4r?