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 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.

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:

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

Here is an example of Procedure:

The Response element encapsulates the handling of the response returned from the VistA system. This response can be handled in 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:

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()

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()

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.

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.

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.