| DESCRIPTION OF ENHANCEMENTS |
VISTA HL7 patch HL*1.6*57 addresses most of the outstanding HL7 1.6
Interfaces are now more intuitive, consistent and simpler regardless of
re-transmissions, the action below will be performed.
200.21 EXCEED RE-TRANSMIT ACTION 200;10 SET
'I' FOR ignore;
'R' FOR restart;
'S' FOR shutdown;
DESCRIPTION: This field determines what to do when a message exceeds
the number of retry attempts for this Logical Link.
the role of the VISTA system as sender or receiver or the mode of
Actions are: Ignore = send alert once and keep trying to resend
Restart = send alert once and shutdown link then start link
Shutdown = send alert once and shutdown link
(2) There is a new entry in HL7 ERROR MESSAGE file, #771.7.
CODE: 109 SHORT TEXT: Duplicate Message
DESCRIPTION: Message has already been received and processed. This is
a duplicate.
communication (Mailman, TCP, serial, local app-to-app). The number of
The following NOIS's are addressed by this patch:
ISF-0499-61219
ISF-0499-61021
BRX-0499-11335
MIA-0499-31927
SAG-0599-42045
ISH-0696-40781
BAY-1099-32639
SLC-1099-51078
BAY-0499-31357
protocol definitions that are required to support a simple interface has
SDC-1099-62397
ISB-1099-31173
BAC-0699-40281
BIG-0999-72027
15. The DATE/TIME field of the HL7 Message Header has been enhanced to
include the timezone offset.
16. New public functions:
been reduced in most cases to just two.
MSGSTAT^HLUTIL(X) ;message status
input value: X = message id
return value: status^status updated^error msg.^error type pointer^
status:
0 = message doesn't exist
1 = pending transmission
1.5 = being transmitted
2 = awaiting application acknowledgement
3 = successfully completed
4 = error
8 = being generated
9 = awaiting processing
MSGACT^HLUTIL(X,HLIENACT) ;outgoing message action
input value: X = message id
HLIENACT = 1-cancel; 2-requeue
return value: 1 = action sucessfull
0 = action failed
CHKLL^HLUTIL(X) ;check setup of Logical Link
3. Redesigned Menu. The HL7 MAIN MENU option has been completely
input value: X = institution name or number
return value: 1 = setup OK
0 = LL setup incorrect
17. New Option: "Validate Interfaces"
Use this option to check your interface setups for potential problems.
Starting with an Event Driver Protocol, the event driver, subscriber(s)
and application definitions will be scanned and a report generated.
reorganized to reflect user preferences both from the field and the JAD
After patch 57 is installed, your pre-57 interfaces will continue to work.
However, you may be interested in upgrading your existing interfaces to
the post-57 style to take advantage of the new features. If you run this
option on a pre-57 setup, you can use the report as a guide for making
modifications. If your post-57 setup results in fewer protocols, be sure
to remove the unneeded protocols. Remember-if the report on a pre-57
interface reports errors, it does NOT mean the interface has been broken
or will stop working because of patch 57. Use the report as a guide only
for upgrading or for troubleshooting an existing POST-57 interface.
Focus Group.
No conversion of existing interfaces that have been properly defined will
be necessary.
Additional details regarding changes to the Application Parameter File,
Event Point Protocols, Subscriber Protocols and key related fields are
defined below.
The following routines are included in this patch. The second line of each
of these routines now looks like:
;;1.6;HEALTH LEVEL SEVEN;<patchlist>;Oct 13, 1995
CHECK^XTSUMBLD results:
Routine Name Before Patch After Patch Patch List
============ ============ =========== ==========
HLCS 5743323 5745388 2,9,14,19,43,57
HLCS2 8763479 10072062 14,40,43,49,57
HLCSAS1 1742491 1743950 43,57
HLCSDL 4174780 4111820 2,44,49,57
HLCSDR 3936049 3904673 2,14,49,57
deficiencies cited by the HL7 Joint Application Development (JAD) Focus
4. Event types for version 2.1 messages are no longer required. HL7
HLCSFMN0 5857525 5857070 15,57
HLCSFMN2 NEW 1942573 57
HLCSHDR 5939243 7364841 37,19,57
HLCSHDR1 6658466 7750238 19,57
HLCSHDR2 NEW 1077600 57
HLCSLM 157679 6371649 49,57
HLCSLNCH 12855635 12643769 6,19,43,49,57
HLCSLSM 154819 191876 49,57
HLCSMM 2776063 2836421 17,35,57
HLCSORAT 5245857 5441831 57
1.6 is now backward compatible to HL7 Standard, version 2.1 transactions.
HLCSRPT3 10792707 10830740 50,57
HLCSTCP 4469052 5152314 19,43,49,57
HLCSTCP1 4899040 4965932 19,43,57
HLCSTCP2 7731395 10328595 19,43,49,57
HLERCHK NEW 12063792 57
HLFNC2 5393929 5397412 2,26,57
HLMA2 3410765 7268935 19,43,57
HLPAT57 NEW 1630585 57
HLSUB 4535863 5277110 14,57
HLTP01 5245980 5262489 2,25,34,47,57
VISTA HL7 version 1.5 interfaces should be upgraded to 1.6 as soon as
HLTP3 12440103 14050232 19,43,57
HLTP31 NEW 1680845 57
HLTP4 7754632 7805100 19,57
HLTPCK1A 7334335 14402537 2,25,34,57
HLTPCK2A 11350701 15262342 19,57
HLUOPT 11331726 11707096 57
HLUTIL 134301 2643574 36,19,57
HLUTIL2 5380198 5387464 19,43,57
List of preceding patches: 14, 15, 26, 34, 35, 43, 49, 50
possible. Version 1.5 fields have been marked for removal from the system.
Sites should use CHECK^XTSUMBLD to verify checksums.
Installation Instructions:
==========================
1. Users are allowed to be on the system during the installation.
2. DSM SITES: Review your mapped set. If any of the routines listed in
the Routine Summary section are mapped, they should be removed from
the mapped set at this time.
Once this occurs, version 1.5 interfaces will no longer function. There
3. Shutdown all Logical Links and incoming and outgoing filers, and
the Link Manager. Use the opitons:
Shut Down All Logical Links
Stop all incoming filers
Stop all outgoing filers
TCP/IP Link Manager Start/Stop
For DSM sites ONLY, if you have an HL7 UCX Service associated
should be no new development using the 1.5 interface method.
with the account(uci/directory) where you are installing this patch,
please disable this service.
4. Use the 'INSTALL/CHECK MESSAGE' option on the PackMan menu. This
option will load the KIDS package onto your system.
5. The patch has now been loaded into a Transport global on your
system. You now need to use KIDS to install the Transport global.
On the KIDS menu, under the 'Installation' menu, use the following
options:
2 Verify Checksums in Transport Global
3 Print Transport Global
4 Compare Transport Global to Current System
5 Backup a Transport Global
6 Install Package(s)
INSTALL NAME: HL*1.6*57
=========
Answer 'NO' to 'Want to DISABLE Scheduled Options, Menu Options,
and Protocols?'.
5. Merger of Split Logical Link and Lower Level Protocol Parameter
6. Startup all Logical Links and incoming and outgoing filers. Use the
'Restart/Start All Links and Filers' option.
For DSM sites ONLY, if you previously disabled an HL7 UCX Service
for this installation, you may now enable it.
7. DSM Sites: Rebuild your mapped set if necessary.
8. Start Link Manager using the option: "TCP/IP
Files. File 870 (Logical Link) and file 869.2 (HL LOWER LEVEL PROTOCOL
Link Manager Start/Stop."
=========================================================================
For a complete and up-to-date set of documents, tutorials and
presentations (and access to the HL7 Standard) please
visit the OpenVista Website (frequently) at:
http://vista2.domain.ext/openvista/
PARAMETER) have been merged into a single file.
At this site, you'll be able to find the new DEVELOPER MANUAL as well as
supplemental information on DYNAMIC ADDRESSING and TCP/IP SUPPORT.
=========================================================================
Interface Configuration with Patch 57
This section explains what has changed with Patch 57, and how the various
files and fields will be used and the new business rules associated with
Group and Part 2 of the OpenVISTA Tactical Plan.
validating a message header.
Event Point Protocols
An event point protocol is a specific type of HL7 protocol defined in file
101. It represents the sending side of a particular HL7 transaction. It
does not have to be a VISTA event point. However, if the event point
originates in VISTA, several fields have been renamed along with changes
to underlying code to more clearly define how VISTA HL7 uses them. When a
message is being generated in VISTA, the header will contain the data from
6. Response message type and event type can now be different from the
these fields and is delivered to each of the subscribers found in the
SUBSCRIBERS multiple. Note that the ITEM multiple is no longer used for
HL7 transactions.
Event Driver Protocol Key Fields
770.1 SENDING APPLICATION (P771), [770;1]
770.3 TRANSACTION MESSAGE TYPE (P771.2'), [770;3]
770.4 EVENT TYPE (P779.001'), [770;4]
770.6 PROCESSING ID (S), [770;6]
initial message's message type/event type pair. The Transaction Message
770.8 ACCEPT ACK CODE (P779.003'), [770;8]
770.9 APPLICATION ACK TYPE (P779.003'), [770;9]
770.95 VERSION ID (*P771.5'), [770;10]
772 RESPONSE PROCESSING ROUTINE (K), [772;E1,245]
775 SUBSCRIBERS (Multiple-101.0775), [775;0]
.01 SUBSCRIBERS (M*P101), [0;1]
Subscriber Protocols
type and Event type are no longer defined on the subscriber protocol for a
This type of protocol contains all of the parameters for and is always
associated with the RECEIVING SYSTEM. The logical link field can be used
to describe a single point-to-point interface between a sending and
receiving system. If this interface included two VISTA systems, the
logical link would always point to the remote system. All other settings
in the interface definition would remain the same on both systems. The
RESPONSE MESSAGE TYPE and EVENT TYPE are now used only for responses.
When a message is received, the following validation checks are performed.
On the receiving system, the HL7 package parses the inbound message header
message to be successfully delivered. This information is now derived from
and identifies the Sending Application, Receiving Application, Message
Type, Event Type and version. If the event type is missing, it validates
that the version is less than 2.2. It validates the sending and receiving
application by checking them against the Application Parameter file. If
they are missing or "Inactive" an error is logged. It then looks up the
Event Driver protocol using the AHL1 cross-reference or, if missing the
event type, uses the new AHL21 cross-reference on file 101. Delivery to
the Subscriber protocol is then based on Receiving Application. An error
is recorded if either the event driver or subscriber protocol cannot be
found. Next, HL7 sets the logical link for the "return path" based on the
the Event Point Protocol only. The Response Message Type and Event Type
entry in the logical link field, (field 770.7). HL7 then checks to see if
the sending and/or receiving facility fields are required for each
application in the transaction (file 771). If the sending or receiving
facility is required and the header is blank an error is logged. If the
facility information in the header differs from data in file 771 an error
is logged. If no data exists in the application parameter file but the
facility information is required, HL7 expects the header to contain the
new default facility data. The receiving facility data is checked against
the receiving system's site parameter settings and the sending facility
data is checked against the logical link definition (file 870). If the
fields are now used for defining the message type and event type of the
sending facility data (Domain name) is present and cannot resolve to a
logical link, an error is logged, otherwise, the logical link of the
sending facility is used as the return path for responses regardless of
how the subscriber protocol logical link field was defined.
Subscriber Protocol Key Fields:
770.11 RESPONSE MESSAGE TYPE (P771.2'), [770;11]
770.2 RECEIVING APPLICATION (P771), [770;2]
770.4 EVENT TYPE (P779.001'), [770;4]
subscriber response.
770.6 PROCESSING ID (S), [770;6]
770.7 LOGICAL LINK (P870'), [770;7]
771 PROCESSING ROUTINE (K), [771;E1,245]
773.1 SENDING FACILITY REQUIRED? (S), [773;1]
773.2 RECEIVING FACILITY REQUIRED? (S), [773;2]
773.3 SECURITY REQUIRED? (S), [773;3]
773.4 DATE/TIME OF MESSAGE REQUIRED? (S), [773;4]
774 ROUTING LOGIC (K), [774;E1,245]
Application Parameter File
This file contains the basic settings needed to describe an application
that either sends or receives a message.
**Note that the fields pertaining to VISTA HL7 version 1.5 have been
marked for removal from the system.
The default field separator is the up-caret ("^") and the default encoding
7. "Report" Option Fixed. The HL7 option, "Report" has been fixed to
characters are "~|\&." Developers are not required to use these defaults.
The preferred characters for the sake of message readability is the
vertical bar ("|") as a field separator and "~^\&" as the encoding
characters. Note that the "^"-character cannot be placed first in the list
due to VA Fileman limitations.
.01 NAME (RFX), [0;1]
2 ACTIVE/INACTIVE (S), [0;2]
3 FACILITY NAME (F), [0;3]
4 MAIL GROUP (P3.8'), [0;4]
properly display non-TCP status codes and errors. The option has been
5 *HL7 SEGMENT (Multiple-771.05), [SEG;0]
.01 HL7 SEGMENT (MRP771.3'), [0;1]
2 FIELDS USED IN THIS SEGMENT (RF), [F;1]
6 *HL7 MESSAGE (Multiple-771.06), [MSG;0]
.01 HL7 MESSAGE (MRP771.2'), [0;1]
1 PROCESSING ROUTINE (RF), [R;E1,17]
7 COUNTRY CODE (P779.004'), [0;7]
100 HL7 FIELD SEPARATOR (F), [FS;E1,2]
101 HL7 ENCODING CHARACTERS (F), [EC;E1,4]
renamed to, "Link Error/Status Report (non-TCP)."
Logical Links
The Logical Link File (870) and the HL LOWER LEVEL PROTOCOL PARAMETERS
file (869.2) have been merged into 870. The pointer from 870 to 869.2 has
been changed to point to file 869.1 (HL LOWER LEVEL PROTOCOL TYPE). Users
may now define parameters for multiple LLP's under the same Logical Link
definition and simply change the "type" pointer as needed. A number of
fields in 869.2 have been removed since the standard does not allow the
settings to be altered. Since there has always been a 1:1 correspondence
of Logical Links to LLP Parameters, users should be able to safely remove
file 869.2 after installing this patch.
Properly Defined VISTA-to-VISTA Interface (Before HL*1.6*57)
The following is an example of a PROPERLY defined point-to-point interface
between two VISTA Systems. In this example, the Sending System initiates
an ADT message to the Receiving System and expects an Acknowledgement.
4.1 Event Point Protocol Stored on Sending System
8. Same-System Batch Messages. It has not been possible to exchange
(Interface Workbench View):
(1) JC ADT SERVER
Text: Test tcp links
Package:
Message Type Rcvd: ADT Accept Acknowledgement: AL
Event Type Rcvd: A01 Application Acknowledgement: NE
Priority: <DEFAULT>
Processing ID: DEBUG
Version ID: 2.3
Entry Action: <NONE>
batch messages between applications running on the same system. This has
Exit Action: <NONE>
Process ACK Routine: Q
Subscribers: JC ADT RECV
(VA FileMan View):
NAME: JC ADT SERVER ITEM TEXT: Test tcp links
TYPE: event driver CREATOR: CLEMENS,JOHN
ITEM: JC ADT RECV
TIMESTAMP: 56930,57258
SERVER APPLICATION: JC ADT SERVER
been corrected.
770.3 MESSAGE TYPE RECEIVED: ADT
770.4 EVENT TYPE: A01
PROCESSING ID: DEBUG
ACCEPT ACK CODE: AL
APPLICATION ACK TYPE: NE
VERSION ID: 2.3
GENERATE/PROCESS ACK ROUTINE: Q
Subscriber Protocol Stored on Sending System
(Interface Workbench View):
(1) JC ADT RECV
Text: TEST SUBSCRIBER USING TCP LINK
Package:
Message Type Rcvd: ACK Sending Facility Required: NO
Message Type Sent: ADT Receiving Facility Required: NO
Event Type Rcvd/Sent: A01 Date/Time of Message Required: YES
Priority: IMMEDIATE Security Required:
Processing ID: DEBUG Logical Link:
Version ID: 2.3
9. Message Header Enhancements to Improve Security. Message headers
Routing Logic: <NONE>
Entry Action: <NONE>
Exit Action: <NONE>
Process Routine: D REC^JCHL7TST
(VA Fileman View):
NAME: JC ADT RECV
ITEM TEXT: TEST SUBSCRIBER USING TCP LINK
DISABLE: YES
TYPE: subscriber
have been enhanced to improve security. It is now possible to identify the
CREATOR: CLEMENS,JOHN
TIMESTAMP: 56930,56581
CLIENT (SUBSCRIBER): JC TEST RECV
770.3 MESSAGE TYPE RECEIVED: ACK
770.4 EVENT TYPE: A01
PRIORITY: IMMEDIATE
PROCESSING ID: DEBUG
VERSION ID: 2.3
770.11 MESSAGE TYPE GENERATED: ADT
GENERATE/PROCESS ROUTINE: D REC^JCHL7TST
source of a message and route (deferred) acknowledgements based entirely
SENDING FACILITY REQUIRED?: NO RECEIVING FACILITY REQUIRED?: NO
DATE/TIME OF MESSAGE REQUIRED?: YES
Event Point Protocol Stored on the Receiving System
On the receiving system, the event point protocol is set up the same as on
the sending system, however, the subscriber protocol must be set up
differently (see below).
1. Exportable Interface Definitions. Class I Interface definitions are
on header information. When enabled, the facility id field contains the
Subscriber Protocol Stored on the Receiving System
(VA Fileman View):
NAME: JC ADT RECV
ITEM TEXT: TEST SUBSCRIBER USING TCP LINK
DISABLE: YES
TYPE: subscriber
CREATOR: CLEMENS,JOHN
TIMESTAMP: 56930,56581
source domain and destination domain as well as the Institution Number.
CLIENT (SUBSCRIBER): JC ADT RECV
770.3 MESSAGE TYPE RECEIVED: ADT
770.4 EVENT TYPE: A01
PRIORITY: IMMEDIATE
PROCESSING ID: DEBUG
VERSION ID: 2.3
770.11 MESSAGE TYPE GENERATED: ACK
GENERATE/PROCESS ROUTINE: D REC^JCHL7TST
SENDING FACILITY REQUIRED?: NO RECEIVING FACILITY REQUIRED?: NO
DATE/TIME OF MESSAGE REQUIRED?: YES
Facility ID follows the HL7 Version 2.3 format, INSTITUTION
Notice that the data for 770.3 and 770.11 must be reversed in order for
HL7 to generate an ACK with the proper message type (ACK~A01) defined in
the header.
If the receiving system is capable of initiating the same transaction to
the sending system in this example, a new set of protocols and unique
sending and receiving application definitions must be supplied.
Properly Defined VISTA-to-VISTA Interface (After HL*1.6*57)
NUMBER_cs_DOMAIN_NAME_cs_"DNS." For improved security, it is now possible
After Patch 57 is installed, you will see the following differences:
On the sending system, field 770.3 and 770.4 of the EVENT POINT PROTOCOL
are used to generate the header of the initial message.
Important consequence: The same setup can be exported to the receiving
system because field 770.11 is correctly defined as "ACK" before and after
the installation of patch 57 and field 770.11 is used to generate the
response. If an ack is not required (as is currently the case for many
to validate a source domain against entries in the logical link file. When
CIRN definitions) for a given interface the subscriber configuration is of
no consequence.
Therefore:
1. No conversion of properly defined interfaces (see above) is
necessary.
2. If the receiving system needs to initiate the same transaction as
well as receive it, the same two protocols can be used for both cases.
valid domain information is present in the message header, the HL7 package
Note that some interface setups may be improperly defined, but work anyway
because of unusual circumstances. All interfaces currently in production
should be reviewed based on this document.
To assist with this, an "interface debugger" routine (^HLERCHK) has been
supplied with patch 57 to examine one or all interfaces.
Use this as a general tool for interface troubleshooting after
installing the patch. It examines each HL7 Event Driver Protocol,
Subscriber Protocols, and Application Definitions and generates a report
of potential problems. It can be used with pre-Patch 57 setups as a guide
for converting an interface to post-57 format. However, if it reports
issues with a pre-57 setup, this should not be interpreted as an
indication that the interface is not set up correctly.
Event Point Protocol (for both Sending and Receiving System)
NAME: JC ADT SERVER TYPE: event driver
CREATOR: CLEMENS,JOHN
DESCRIPTION: Testing message transmissions
(1) attempts to resolve the domain to the corresponding logical link and
SENDING APPLICATION: JC NXT SEND
770.3 TRANSACTION MESSAGE TYPE: ADT
770.4 EVENT TYPE: A01
PROCESSING ID: PRODUCTION
ACCEPT ACK CODE: AL
VERSION ID: 2.2
PROCESSING ROUTINE: Q
RESPONSE PROCESSING ROUTINE: Q
SENDING FACILITY REQUIRED?: YES
RECEIVING FACILITY REQUIRED?: NO
SUBSCRIBERS: JC ADT RECV
Subscriber Protocol (for both Sending and Receiving System)
NAME: JC ADT RECV TYPE: subscriber
CREATOR: CLEMENS,JOHN
RECEIVING APPLICATION: JC KRN REC
770.3 TRANSACTION MESSAGE TYPE: ADT
770.4 EVENT TYPE: A01
PROCESSING ID: PRODUCTION
(2) uses this information as the return path for responses in place of
VERSION ID: 2.2
770.11 RESPONSE MESSAGE TYPE: ACK
PROCESSING ROUTINE: Q
SENDING FACILITY REQUIRED?: NO
RECEIVING FACILITY REQUIRED?: NO
now exportable to all VISTA systems with little or no modification at the
what may be defined in the Protocol file, Logical Link field.
10. Message Header Enhancements Facilitate Message Broker Integration.
Enhancements to message header also facilitate the integration of Message
Brokers into our Enterprise Application Integration strategy. In a future
enhancement, it will be possible to query a DNS for current IP
information. Note that any data that currently exists in the HL7
Application Parameter file (771), Facility ID field, overrides this
enhancement. Data for the 'default' Sending Facility ID (if required and
no Application Parameter is defined) is derived from the HL7 Communication
site.
Server Parameter file and edited using the option, Edit Site Parameters.
Data for the Receiving Facility ID field is derived from the HL7 Logical
Link File (870).
11. Processing ID Field Checking. Another improved security feature
includes a check of the processing id field against the protocol
definition or the site parameter file. On the receiving system, a mismatch
between the message and the local definition results in an error. This can
prevent test or debug messages from being processed in production
accounts, and vice versa.
12. Startup and Shutdown Enhancements. A new option has been created,
"Stop All Logical Links And Filers". The "Restart All Links And Filers"
option has also been fixed; it was shutting down all links, and then
restarting only those links with AUTOSTART ENABLED. Now only AUTOSTART
links are shut down and restarted.
13. Interface Workbench Replacement. The former HL7 option, "Interface
Workbench," has been replaced. Due to the HL7 package's underlying
architecture, it is relatively unintuitive to use and has been a problem
2. Reduction in Interface Development, Testing and Activation Time.
to maintain. The new user interface also eliminates 21 routines and 62
protocols.
14. Message Synchronization Over TCP. When a connection is broken it is
possible for subsequent transactions to get out of synch. A fix is
provided to assist with re-synchronizing the two systems. The following
changes were added:
(1) A new field has been added to the HL LOGICAL LINK file, #870. When a TCP
client exceeds the parameter value for the maximum number of
|
