Overview

The OVID (OpenVista Interface Domain) layer is a set of development tools designed to enable software developers easier access to OpenVista data.  Currently, we've implemented a set of java domain classes that demonstrate how this can be accomplished.

If you've ever wanted to call an OpenVista RPC from java, then this tool would be of interest to you.

If you've ever wanted to construct a fileman call in java because you can't find a suitable, existing RPC, then OVID would be of interest to you.

OVID is basically an RPC resource messaging interface with java bindings.  OVID can execute an RPC and get the results.  It is up to the developer to construct the call and glean the results into a usable format.  Further, OVID contains mumps routines and a specialized RPC that can invoke Fileman on behalf of the caller.  RPC and Fileman "modes" can be easily intermixed.

OVID current uses VistaLink as its network transport.  In the near future, it will also support RPCBroker as a optional transport.

RPC Example

Consider the following example.  You want to write a java application that uses the ORRC DASHBOARD PATIENTS RPC to get a list of patients on a unit.  Details of the inputs and outputs for this RPC can be found here.  For our purposes, we'll assume that we know that the ward IEN is 1 and that we want a Nursing list (type 'N').  We can make this call with the following code:

...
// get a connection to the vistalink broker, 8002 is the vistalink port
connection = getConnection("vistalinkhost", "8002", "accesscode", "verifycode");
 
String wardID = "2";
String duz = "1";
 
// get a connection from vistalink
RPCConnection rpcConnection = new VistaLinkRPCConnection(connection);
rpcConnection.setContext("MSC PATIENT DASHBOARD");
VistaRPC dashboard = new VistaRPC("ORRC DASHBOARD PATIENTS", ResponseType.ARRAY);
// set up input arguments
dashboard.setParam(1, duz);
dashboard.setParam(2, "N");
RPCArray wardInfo = new RPCArray();
wardInfo.put("1", "W:" + wardID);
dashboard.setParam(3, wardInfo);
// execute the RPC
RPCResponse response = rpcConnection.execute(dashboard);
// get the response
String items[] = response.getArray();
for (String item : items) {
     System.out.println(item);
}
...
 

OVID defines classes for VistaLink connections and authentication, RPC connections/contexts, RPC inputs and responses.

Fileman Example

OVID also has the ability to use Fileman in silent-mode.  The follow snippet shows using low-level routines to accomplish retrieving the the GENERIC NAME, NDC and MESSAGE field from the DRUG file (50) for IEN 2.

...
// get a connection to the vistalink broker
vconn = getConnection("host", "port", "access", "verify");
 
RPCConnection connection = new VistaLinkRPCConnection(vconn);
try {
    connection.setContext(FMUtil.FM_RPC_CONTEXT);
} catch (RPCException e) {
    throw e;
}
ResAdapter adapter = new RPCResAdapter(connection, FMUtil.FM_RPC_NAME);
 
FMResultSet results;
FMRecord drug = new FMRecord("DRUG");
drug.setIEN("1");
FMRetrieve query = new FMRetrieve(adapter);
query.setRecord(drug);
query.addField("NDC", FMField.FIELDTYPE.FREE_TEXT);
query.addField("GENERIC NAME", FMField.FIELDTYPE.FREE_TEXT);
query.addField("MESSAGE", FMField.FIELDTYPE.FREE_TEXT);
try {
    results = query.execute();
    System.out.println(drug.getIEN() + " : " + drug.getValue("GENERIC NAME") + " : " + drug.getValue("NDC") + " : " + drug.getValue("MESSAGE"));
}
...

Here is how a value can be updated via fileman...

RPCConnection connection = new VistaLinkRPCConnection(vconn);
try {
    connection.setContext(FMUtil.FM_RPC_CONTEXT);
} catch (RPCException e) {
    throw e;
}
ResAdapter adapter = new RPCResAdapter(connection, FMUtil.FM_RPC_NAME);
 
FMResultSet results;
FMRecord drug = new FMRecord("DRUG");
drug.setIEN("1");
FMRetrieve query = new FMRetrieve(adapter);
query.setRecord(drug);
query.addField("NDC", FMField.FIELDTYPE.FREE_TEXT);
query.addField("GENERIC NAME", FMField.FIELDTYPE.FREE_TEXT);
query.addField("MESSAGE", FMField.FIELDTYPE.FREE_TEXT);
try {
    results = query.execute();
    System.out.println(drug.getIEN() + " : " + drug.getValue("GENERIC NAME") + " : " + drug.getValue("NDC") + " : " + drug.getValue("MESSAGE"));
    String saveMessage = drug.getValue("MESSAGE");
 
    FMUpdate update = new FMUpdate(new RPCResAdapter(connection, FMUtil.FM_RPC_NAME));
    FMDrug updateDrug = new FMDrug();
    updateDrug.setIEN("1");
    drug.setValue("MESSAGE", "This is a test message");
 
    update.setEntry(drug);
    results = update.execute();
 
    //set it back to the original value
    updateDrug = new FMDrug();
    updateDrug.setIEN("1");
    drug.setValue("MESSAGE", saveMessage);
    update.setEntry(drug);
    results = update.execute();
}
...

Further, we've developed annotations that make it simple to create beans that can interact with our fileman layer.  We'll be documenting this functionality with series of tutorials.

How To Find RPCs

A good resource for determining what RPCs are generally available in OpenVista, and generally good documentation of their inputs and outputs can be found at: http://medsphere.org/docs/vista-rpcs/.

Next Steps

OVID is an active project within Medsphere.  Check back soon as we'll be documenting some tutorials to aid in creating domain objects using OVID.

Next on our list for development (at this time) is:

• Create a comprehensive set of acceptance tests.  Right now, our tests are spread out and not validated.  Having these tests will allow us to quickly add new classes while validating current functionality.
  
• Refactor the connection logic to make it easy to choose between RPCBroker and VistaLink.  RIght now, we are reliant on VistaLink.  RPCBroker would be a better choice for some platforms.
• Refactor the FM logic to enable richer queries.
• We're readying the codebase to be placed in an online repository to make it easier to collaborate.