VistA ADT Filer
Installation, Setup and Technical Guide
PO Box 80275
Charleston, SC 29416
Table of Contents
Installing from KIDS 3
Overview 4
Acknowledgement Messages ...………………………………………………………...... 7
Service User 9
ADT Filer Main Menu Option .10
Primary Patient ID .12
Create / Edit SISIADT HL7 INTERFACE PARAMETER 15
Create / Edit SISIADT AUXILIARY FIELD MAP 24
ACCOUNT NUMBER 29
How ADT Filer Interprets events…………………………………………………………………... 33
ADT Filer (Kernel) PARAMETERS 36
Application Programmer Interface 57
Miscellaneous Events Support 62
ADT Filer Utilities 65
Translating HL7 Field Values (SISIADT CONSTANTS) 70
Post-Events Processing 74
Custom Post-event Example 75
Purge Exceptions Scheduled Option 77
VistA HL7 Infrastructure 78
ADT Filer Routines and Entry Points……………………………………………………………... 81
ADT Filer Graphical User Interface (Deprecated)……..………………...…………………… 112
Exceptions Context and Log Mode …………………………………………….………………... 118
Common Fatal Exceptions ………………………………………………………………………. 126
Meaning of Exception Codes ……………………………………………………………………... 128
ADT Filer Version 2 Installation Checklist 177
Summary of HL7 to VistA Data Dictionary Mappings 179
Troubleshooting and Problem Solving 182
Exporting and Importing Configuration Settings 192
Testing a New Interface 194
Load Testing Option…………………………………………………………….……………………196
Uninstalling the ADT Filer 204
[Note] Table of Contents page numbers may be offset while document is being revised.
VistA ADT Filer[1],[2]
Installation, Setup and Technical Guide
The VistA ADT Filer[3] is a licensed software application from Sea Island Systems, Inc., distributed as a VistA KIDS[4] file. The exact file name varies with version and patch level but willv generally have a form similar to the following:
SISIADTJpKx.KID
where J.K is the version and x the sub-version. The letter “p” stands for “point” as in decimal point. Special field-test versions of the KIDS file may have the following form:
SISIADT-FACILITY-Txx.KID
where FACILITY identifies the field test location and xx the test revision counter.
To install the VistA ADT Filer invoke the VistA KIDS Installation options: “Load a Distribution” and “Install Package(s).” It is not necessary to disable options or protocols, or to inhibit logons. However, answer YES to the prompt, “Want KIDS to Rebuild Menu Trees Upon Completion of Install?” See also the “ADT Filer Version 2 Installation Checklist” section of this document for additional details.
Install patches in sequence number order for the version of the ADT Filer installed. Patches and their corresponding release notes may be downloaded from: http://www.seaislandsystems.com/ADTFiler. Be sure to read release notes prior to installing patches, in case any special preparations are needed.
Overview
The ADT Filer interface uses the VistA HL7 1.6 infrastructure to receive messages from a “foreign system,” that is, from a system that serves as the master ADT or Financial system, and is the authoritative source of information about patient demographics, present location, future appointments, and so forth. The VistA receiver of HL7 ADT information may be regarded as the authoritative source of selected clinical information about the patient, but is not the authoritative source for administrative information.
ADT Filer
The flow diagrams on the preceding page illustrate the outermost layers of the ADT Filer interface. The nuts and bolts of the interface belong to the container labeled, “Process in Foreground or Background” at the bottom of the diagrams. This part of the interface is called “Event Processing.” It is the part that files patient demographics, visits and admissions, and optionally other data relevant to the patient’s record in VistA.
The foreground part of the ADT Filer interface receives the HL7 message from the VistA HL7 infrastructure. At this point it creates or updates the patient’s account in VistA, i.e., the ADT Filer’s ACCOUNT NUMBER file (#29320.8), if appropriate. It also parses and translates the HL7 message. By “translate” is meant that it applies whatever rules or translation tables are specified in the SISIADT CONSTANTS file (#29320.7) and that correspond to segments and fields or components that are present in the ADT event message. After completing these preliminary processing steps and calling Taskman to schedule event processing, the ADT Filer generates an accept acknowledgement, if required.
The outline reproduced in the next page summarizes the relationship between the VistA HL7 infrastructure and the ADT Filer interface.
The ADT Filer includes many in-line rules for processing each ADT event type supported by the interface. However, in addition to these in-line or hard-coded rules, the ADT Filer also includes parameters that can be used to modify the way in which events are processed, and to customize processing on a sender-by-sender or site-by-site basis. Details of these parameters and other important implementation matters are presented in the following pages.
Acknowledgement Messages
The ADT Filer does not generate or transmit deferred acknowledgement messages. However, it does call GENACK^HLMA1 to return an accept acknowledgement to the sender via the open TCP/IP channel (the received message channel), if the received MSH (field 15) and ADT Filer parameter settings so indicate. The following table summarizes how acknowledgement rules are applied in the ADT Filer context.
MSH.15 / VistA HL7 / ADT FilerAL / Always ACK / Do not ACK (duplicate)
NE / Never ACK / Never ACK
ER / Ignore
SU / Ignore
Empty / Never ACK / ACK if and only if the parameter SISI ENABLE APPLICATION ACK is true.
In addition to the parameter SISI ENABLE APPLICATION ACK, the ADT Filer can also insert a delay before generating an acknowledgement. The delay in seconds is specified as the value of the parameter SISI APPLICATION ACK DELAY.
ADT Filer Acknowledgement Process
In addition to parameters listed on the preceding page, the ADT Filer Master Switch also affects acknowledgements. See the SISI MASTER SWITCH parameter description.
Finally, The ADT Filer does not generate acknowledgements in debug mode (parameter SISI DO NOT TASK EVENTS valued true).
After installing the ADT Filer, unless importing a configuration from another implementation, it is necessary to perform several preliminary setup steps.
SERVICE USER
Use the standard VistA option “Add a New User to the System” to add a user such as FILER,ADT or INTERFACE,ADT or etc., that will serve for attribution of activities performed by the ADT Filer. This user should not have a primary menu or logon access and verify codes assigned. The following is an example:
NAME: FILER,ADT INITIAL: HL7
SEX: MALE
PREFERRED EDITOR: SCREEN EDITOR - VA FILEMAN
DATE ENTERED: MAR 11,2010 CREATOR: MILLIGAN,LLOYD
SSN: 800000001
NAME COMPONENTS: 200 SERVICE/SECTION: IRM
SIGNATURE BLOCK PRINTED NAME: ADT FILER
SISIADT OVERALL
Menu Option
Assign the SISIADT OVERALL menu to the user who will be responsible for configuring the ADT Filer (or use routine ^XUP to access this menu). Most configuration steps can be performed using sub-options of this menu.
HL7 ADT Filer Overall Menu (SISIADT OVERALL)
|
|
----1 System Definition Menu ------1 Enter/Edit AUX Field Map
[SISIADT SYSTEM DEFINITION MENU] [SISIADT AUX FIELD MAP EDIT]
|
|------2 Enter/Edit ADT Filer HL7
| Interface Parameter [SISIADT
| HL7 INTERFACE EDIT]
|
|------3 Check ADT Filer Configuration
| [SISIADT CHECK CONFIGURATION]
|
|------4 Create/Edit Table of Constants
| [SISIADT CONSTANTS EDIT]
|
|------5 Export / Display Configuration
| Settings [SISIADT EXPORT
| CONFIGURATION]
|
|------6 Import and File Configuration
| Settings [SISIADT IMPORT
| CONFIGURATION]
|
|------7 Enable/Disable selective audit
| [SISIADT AUDIT]
|
|------8 Delete ADT Filer Configuration
Settings [SISIADT DELETE
CONFIGURATION]
**LOCKED: SISIADT MGR**
----2 ADT Filer PARAMETERS menu ------1 Message and Interface
[SISIADT PARAMETERS MENU] parameters [SISIADT MESSAGE
| AND INTERFACE]
|
|------2 Event-based parameters edit
| [SISIADT EVENT PARAMETERS]
|
|------3 Segments and Fields parameters
| [SISIADT SEGMENTS AND FIELDS]
|
|------4 VistA-based parameters
| [SISIADT VISTA PARAMETERS]
|
|------5 Miscellaneous Parameters edit
[SISIADT MISC PARAMETERS]
----3 Display Options [SISIADT ------1 Display HL7 ADT Filer
DISPLAY OPTIONS] Configuration [SISIADT DISPLAY
| CONFIGURATION]
|
|------2 Print ADT Filer Exceptions
| [SISIADT PRINT EXCEPTIONS]
|
|------3 Show HL7 message [SISIADT
| MESSAGE DISPLAY]
|
|------4 Display last ADT Filer patch
| installed [SISIADT DISPLAY
| LAST PATCH]
|
|------5 Chronological Transactions for
| Patient [SISIADT TRANSACTION
| CHRONOLOGY]
|
|------6 List ADT Filer Parameter
| Settings [SISIADT LIST
| PARAMETERS]
|
|------7 Message processing summary
[SISIADT MSG PROCESSING
SUMMARY]
----4 Utility options [SISIADT ------1 Reprocess ADT Filer HL7
UTILITIES MENU] Message [SISIADT REPROCESS HL7
| MESSAGE]
|
|------2 Point ACCOUNT NUMBER to
| movement/visit [SISIADT POINT
| ACCOUNT NUMBER]
|
|------3 Find an exception for a
| message control ID [SISIADT
| FIND CONTROL ID]
|
|------4 Load Test ADT-A04 Generator
[SISIADT LOAD TEST]
**LOCKED: SISIADT MGR**
Primary Patient ID
Auxiliary field map
One of the most important functions performed by the interface is to identify the patient. When a new patient is registered the patient’s primary ID (medical record number or etc.) must be stored in VistA. Similarly, when information about an existing patient is received, the ADT Filer must determine the correct identity of the patient. Failure to do so could result in registering a duplicate patient.
How the ADT Filer resolves the identity of an existing patient will be explained in the COMPUTE DFN paragraph of the following section.
VA VistA identifies patients by social security number (SSN). However, this identifier is not normally suitable for non-VA VistA implementations. Usually the patient has one immutable identifier, but sometimes more than one. In the latter case, identifiers are usually location-specific.
Three main strategies exist for storing the patient identifier or identifiers. First, the implementation may add an indexed field to the VistA PATIENT file, store the identifier there, and use that field for patient lookup in the COMPUTE DFN logic. Second, the implementation may use the PATIENT/IHS file (#9000001), HEALTH RECORD NO. multiple to store one or more than one location-specific patient ID.
Third, the implementation may use a custom ID storage strategy, possibly a different multiple than the HEALTH RECORD NO. sub-file of the PATIENT/IHS file, or a different file entirely.
The second and third strategies enumerated in the preceding paragraph involve an ADT Filer PARAMETER setting and an IMPLEMENTATION-SPECIFIC API, respectively. They will be explained in more detail later in this Guide.
The first strategy, to use an indexed field in the PATIENT file (or another file that relates unambiguously to the PATIENT file) will be described here, because if this strategy is employed it is necessary to define a Primary Patient ID auxiliary field map and then to specify its name in the SISIADT HL7 INTERFACE PARAMETER file, which will be discussed in the next section.
To create a new auxiliary field map, use the following option:
HL7 ADT Filer Overall Menu (SISIADT OVERALL)
|
|
----1 System Definition Menu ------1 Enter/Edit AUX Field Map
[SISIADT SYSTEM DEFINITION [SISIADT AUX FIELD MAP EDIT]
MENU]
Respond to prompts as appropriate for the file and field# that will be used to store the primary patient ID. The following is only an example. Note that each implementation may use different HL7 data sources or different target file/field# combinations. User responses are colored red.
Select System Definition Menu Option: Enter/Edit AUX Field Map
EVENT DRIVER PROTOCOL: SISIA ADT-A04 SERVER Foreign System Interface ADT-A04 Server
HL7 SEGMENT: PID Patient Identification
HL7 SEQUENCE: 3
HL7 COMPONENT: 1
HL7 SUBCOMPONENT:
HL7 DATA TYPE: ST String
FILEMAN FILE: 2
FILEMAN FIELD: 29320 Note: This is an example only!
IENS: SISIDFN_","
IENR(1):
CUSTOM TRANSFORM:
SCREEN:
ORDER: -1
EXTERNAL:
SAVEIENS:
FIND:
BRIEF DESCRIPTION: Primary patient ID [Example]
Select FRIEND PROTOCOL: SISIA ADT-A05 SERVER Foreign System Interface ADT-A05 Server
Are you adding 'SISIA ADT-A05 SERVER' as a new FRIEND PROTOCOL (the 1ST for this SISIADT AUXILIARY FIELD MAP)? No//Y (Yes)
ORDER: -1
IENS: SISIDFN_","
Select FRIEND PROTOCOL: SISIA ADT-A01 SERVER Foreign System Interface ADT-A01 Server
Are you adding 'SISIA ADT-A01 SERVER' as a new FRIEND PROTOCOL (the 2ND for this SISIADT AUXILIARY FIELD MAP)? No// Y (Yes)
ORDER: -1
IENS: SISIDFN_","
Select FRIEND PROTOCOL:
Primary Patient ID
Other Considerations
If the primary patient ID will be filed to the Health Record No. multiple of the PATIENT/IHS file, or to an implementation-specific multiple that similarly depends on location, the ADT Filer must be able to identify the facility to which the identifier belongs, both at the time of filing and when looking up an identifier.
The link to VistA facility is accomplished by referring to the “sending facility” field of the message header, and using this value to identify the corresponding VistA INSTITUTION (File 4) entry. The convention is to make the “sending facility” value an identifier of the INSTITUTION entry, for the “ADT FILER” coding system.
Refer to multiple field #9999 in File 4 for each entry that corresponds to a facility (receiver of ADT transactions). Create an entry in this multiple named ADT FILER and insert as the ID value the same exact string (case-sensitive) as is found in the MSH “sending facility” field (for that facility). The ADT Filer uses a special cross-reference to identify the VistA INSTITUTION from this value.
The HEALTH RECORD FAC. field in File 9000001 is DINUM’ed to File 9999999.06, which in turn is DINUM’ed to File 4.[5] Other location-based identifier schemes may refer directly or indirectly to File 4.
Several patient ID convenience functions may be found in routine ^SISIADFN. One must take care, however, to avoid calling a patient ID function recursively (i.e. inadvertently through a chain of ID calls).
Finally, the implementation may use (or not) the social security number. Default social security number validation code is included at VSSN^SISIAUTL. This code first looks for an implementation-specific SSN API in File 29320.75. The user-defined API is invoked if it exists. Otherwise, the default code rejects various known test SSN formats. If SSN is important in the implementation, it is recommended to use an implementation-specific API to override and strengthen the ADT Filer’s built-in validation.
As of patch SISIADT*2.0*17 the order of SSN validation steps when processing a Patient Information Update (ADT-A08) is: 1) Validate the message value for SSN (as received by the ADT Filer’s update event processing code), 2) compare the validated message SSN to the value that is stored in the patient SSN (field# .09). The purpose of this validation sequence order is to prevent unnecessary and unwanted SSN updates when an implementation-specific identifier has been intentionally substituted for SSN in the VistA PATIENT file SSN field.