Log out?

VistA RPC XL

PilotFish VistA RPC XL User Guide

Table of Contents

  1. Introduction
  2. Use With XSLT
  3. Quick Overview
  4. Declaration
  5. API XL Content
  6. VistA RPC XL Component Overview

    1. RPC Calls
    2. General Workflow
    3. Utility
  7. RPC Calls

    1. RemoteProcedure
    2. Procedure

      1. ProcedureString
      2. Parameters
      3. Context
    3. Response
  8. Response API
  9. Listener & Transport API

    1. Connection
  10. Supported Formats
  • Introduction

VistA RPC XL is an XML evaluation and execution system for making complex RPC calls to a VistA system. It allows for running any number of RPC calls in sequence, passing data between them, and outputting the response from the RPCs in an easy to parse format.

VistA RPC XL benefits from a powerful set of tools that can be used around the actual RPC calls, such as flow control, iteration, conditional logic, exception handling, outputting data, etc. It also has the ability to simply and effectively express any RPC call needed.

This document will explain how to use all of VistA RPC XL’s features so that this tool can be used effectively within the PilotFish application.

  • Use With XSLT

In many cases, VistA RPC XL will be generated using XSLT in the PilotFish Data Mapper. In many ways, VistA RPC XL is very similar in concept to XSLT: a series of special XML elements that provide instructions to a Processor that evaluates them. Because of how XSLT can dynamically build an output Format based on the values in an input format, it is ideal to use the Data Mapper to generate VistA RPC XL using the data coming in.

However, it is important to always be aware that VistA RPC XL and XSLT are completely independent of each other. They are each evaluated separately, by totally separate components. The XSLT created by the Data Mapper is evaluated during the XSLT Transformation stage, whereas the VistA RPC XL is evaluated by a subsequent stage, usually the PilotFish VistA RPC XL Transport.

This means that any XSLT instruction elements will only be used for creating the VistA RPC XL document, and will not be present when the VistA RPC XL is being evaluated. A good example would be iteration. An <xsl:for-each /> element will be used by the XSLT Transformation to produce XML output during its iteration. A <http:Iterate /> (covered later in this document) element will achieve the same iteration, but it will run only later when the VistA RPC XL is evaluated.

The simple rule of thumb is that anything with the XSLT namespace prefix will only be present for the XSLT Transformation, while anything with the VistA RPC XL namespace prefix will only be evaluated later on.

  • Quick Overview

This is a quick overview of what a VistA RPC XL document looks like and the basic features of how it works. All of these elements will be explored in more detail.

  • Declaration

To use VistA RPC XL, a root element must be declared. This element must also have the VistA RPC XL namespace.

  • API XL Content

There are many features of VistA RPC XL that are shared with API XL. This includes variables, dynamic expressions, conditions, iteration, and utility features like logging and exception handling. Please feel free to consult the API XL user guide for information on these features.

  • VistA RPC XL Component Overview

This is quick overview of the categories of components that are a part of the VistA RPC XL structure.

  • RPC Calls
The core of VistA RPC XL is being able to execute RPC calls. This is accomplished through RemoteProcedure elements, which allow for configuring all features of RPC calls.
  • General Workflow
These are elements that assist with building the overall workflow of the document. Things like iteration, variables, output, and more all fall into this category.

NOTE: The documentation for these features can be found in the API XL user guide, as they are identical.

  • Utility
Utility elements include logging and exception handling. These are simply additional features that can assist with debugging and edge cases that might be encountered.

NOTE: The documentation for these features can be found in the API XL user guide, as they are identical.

  • RPC Calls

The main purpose of using VistA RPC XL is to make RPC calls. This section describes how to configure the RPC calls.

  • RemoteProcedure
Every RPC Call begins with declaring a RemoteProcedure. This element wraps around both the Procedure call itself, which can be considered a request, and the Response that is returned from the VistA system.

Here is an example of the structure of a RemoteProcedure:

  • Procedure
The Procedure element encapsulates the configuration for the RPC itself. It has two child elements: ProcedureString and Parameters.

Here is an example of Procedure:

  • ProcedureString
The ProcedureString element contains the actual procedure call in its “value” attribute. Any RPC that exists on the Target system is valid here.

Here is an example of ProcedureString:

  • Parameters
The Parameters element wraps around the parameters being submitted with the RPC calls. Parameters are added to the RPC in the order that they are listed here. There are several different types of parameters.

EmptyParameter

The EmptyParameter element is a placeholder that includes no value, and is used to refer to a parameter that should be blank.

EncryptedParameter

The EncryptedParameter element provides an encrypted value for the RPC call via its “value” attribute.

GlobalParameter

The GlobalParameter element uses a key and value to describe its parameter, specified in the “key” and “value” attributes.

ListParameter

The ListParameter element has a collection of values, represented by ParameterPart elements. Each part has a key and a value, specified in the “key” and “value” attributes.

ReferenceParameter

The ReferenceParameter element has a single reference value in its “value” attribute.

LiteralParameter

A LiteralParameter provides a single value through its “value” attribute.

  • Context
The Context element is optional. By default, the context for the RPC call is set on the VistA RPC Listener or Transport that is executing this document. However, if for some reason contexts need to be set on an RPC by RPC basis, these elements can be used. The Context value set here will override whatever was set on the Listener/Transport for this one RPC. If unused, the value set on the Listener/Transport will be used.

Here is an example of Context:

  • Response
The Response element encapsulates the handling of the response returned from the VistA system. This response can be handled a number of different ways.

First and foremost, the Response string is internally transformed into a Java object, with each record and field broken down so that they can be individually accessed using OGNL expressions. This object is exposed as a variable, with its name specified in the “as” attribute. If only the original string value of a response is needed, the object will be automatically converted back to that string when it is outputted. For more info on this object, please consult the relevant section in this document.

In addition, the response can be instantly transformed to other Formats, such as XML, using the “formatAs” attribute. There are a set of encodings that a Response object can be automatically transformed into, specified in a later section, and if any of them are provided to this attribute, the variable exposed by “as” will be in that format.

Lastly, Response elements are considered to be execution scopes. This means that additional RPC calls and other logic can be nested inside of a Response element.

Here is an example of a Response element:

  • Response API

The response from the VistA system is automatically transformed into a Java object, so that its individual fields and records can be accessed using OGNL expressions. This section describes the API of that object to help create those expressions.

  • Response Object
When a VistA response is received, the Response object is created. Internally, it breaks up the string response into a list of Record objects, each one representing a different line in the response. The API of the Response object revolves around providing easy access to that list of Record objects inside of it.

The Response is Iterable, meaning it can be passed to an Iterate element and each Record inside will be exposed during the iteration. This tends to be one of the easiest ways of working with a Response, if something needs to be done with each Record that came back.

If the Response is passed directly to an Output tag with no other formatting specified, the original String version of the response will be outputted.

The Response object also has several helpful methods that can be called individually using OGNL expressions.

  • Record getRecordAt(int index)

    This method retrieves a specific record from the response. The index refers to the ordered position the record was in, and it is 0-indexed, meaning the first record has an index of 0.

    Example: ognl:#response.getRecordAt(0)

  • int getRecordCount()

    This method retrieves a count of all the records in the response as an integer.

    Example: ognl:#response.getRecordCount()

  • Record Object
When the Response object is created, each record in the response is parsed into a Record object. Each Record object contains a list of Strings that represent the individual, caret-delimited fields from the record. The API of the Record object revolves around providing easy access to that list of fields inside of it.

Individual record objects are accessed either through the getRecordAt(index) method on the Response object or through iterating over the Response object.

The Record is Iterable, meaning it can be passed to an Iterate element and each String field inside will be exposed during the iteration. If something needs to be done with each field in the Record, this can be an easy way of working with it.

If the Record is passed directly to an Output tag with no other formatting specified, the original String version of the record will be outputted.

The Record object also has several helpful methods that can be called individually using OGNL expressions.

  • String getFieldAt(int index)

    This method retrieves a specific field from the record. The index refers to the ordered position the field was in, and it is 0-indexed, meaning the first record has an index of 0.

    Example: ognl:#record.getFieldAt(0)

  • int getFieldCount()

    This method retrieves a count of all the fields in the record as an integer.

    Example: ognl:#record.getFieldCount()

  • Listener & Transport API

The VistA RPC XL documents are executed by VistA RPC Listeners & Transports. These modules require some additional configuration in order to be used. The following is a summary of the most important configurations of each module.

  • Connection
The only required configurations for the VistA RPC Listeners & Transports is the connection. A host, port, access code, and verify code for the VistA system must be provided. In addition, a context must be selected, either from the provided list or manually inputted through the custom context field.

  • Evaluation Logging
While disabled by default, the Evaluation Logging option will dump a lot more information to the PilotFish logs about how the RPCs are executing. This is very useful when trying to debug an issue with the VistA RPC XL.

  • Other Options
A few optional configurations are available on the Basic tab. An input file with the VistA RPC XL document can be specified, rather than passing it in via the PilotFish TransactionData. In addition, the document can be strictly validated against the VistA RPC XL schema as another way to catch any potential errors.

Transport Only: One final option applies to the Transport only. If the response from the VistA system should be handled by another Route, a Response Listener can be configured. This is a Programmable Listener in another route that the response of executing the VistA RPC XL document should be sent to.

  • Supported Formats

When handling VistA RPC responses, the response can be automatically transformed from its original state into another format, using the “formatAs” attribute on the Response and Output elements. The following is a list of the supported formats that it can be transformed into.

“string”: this just treats the data as a String with the default system encoding.

“stream”: this is a simple binary stream, or blob. It can contain anything within it.

“cache”: this is a PilotFish Cache object, which provides a flexible and dynamic way of handling binary content.

“xml”: this is XML content, either an XML String or a DOM construct.

“base64”: this is for Base64 encoded content.

This is a unique website which will require a more modern browser to work! Please upgrade today!

Thanks!

Our editors are notified.

Close