Hospitality Suite HL7 ADT/Diet Order Interface User...

Hospitality Suite HL7 ADT/Diet Order Interface

User Guide

Created January 6, 2004 Computrition Software Systems 1 Revised 09/11/2008

Introduction The HL7 Interface provides a graphical user interface that gives you an easy way of monitoring the operation and status of the interface. You can access this user interface by using the web browser on your local PC or workstation. It provides you with an overview of the interface activity including incoming and outgoing message counts, error and warning status, and the ability to view low-level (network status, internal errors, etc) log files as well as the ability to shut down the interface. The interface can also be configured to use its original text-mode interface, should a customer desire it. In the sections below, we discuss how to start, monitor, and stop the HL7 interface in both the original text-mode environment, as well as the web-based graphical environment. To learn about using the original text-based environment see the section entitled Using the Text-Based UI. To learn about using the web-based graphical user interface see the section entitled Using the Web-Based Graphical UI and sections following. In addition, Appendix A contains some hints and tips for maintaining a Hospitality Suite system when it is being used in conjunction with the HL7 interface. Appendix B contains some technical and licensing information on internals of the HL7 interface as well as information about using the https protocol for secure browsing.


Using the Web-Based Graphical UI Starting the interface Follow the steps below to start the interface program: • Login on the interface server computer GUI screen using the username and

password provided—usually the username will be “interface”. (note that the graphical login is not required, you can just as well use one of the text-mode virtual consoles on the interface server machine for this purpose, or you can use a SSH (Secure Shell) connection from another computer—such as “putty” which is available for Windows.)

• Open a text command screen (click on the screen icon at the bottom, or right-click on the desktop and choose “Open terminal”)

• To start the interface type: ./HS_interface<enter> You should see a screen similar to the following (Figure 1):

Figure 1 The HL7 interface is now running “in the background” (detached from this terminal) so you may log off this session if you wish.


Using the Web-Based Graphical UI Whenever the HL7 interface is running it acts as a web server that makes certain internal information available to you through your web browser. You access the User Interface (UI) by browsing to the URL: http://interfaceserver:8080 or

https://interfaceserver:8080 where “interfaceserver” is the hostname (or IP address) of your interface server computer. The “:8080” identifies the “network port” that the server is using to listen for browser connections. (This port number will be set to 8080 unless you request a different value when we configure your interface server computer.) If your interface is configured to use the https protocol for its web-based UI (a new capability with HS 17.5), you will need to enter “https” instead of “http” as shown in the second example above. The https protocol provides for secure, encrypted web browsing. Your entire browser session will be encrypted. When configured to use https the interface enables two additional functions (described later in this document) that allow you to view patient-specific information, and which are helpful in diagnosing problems. Before you can use the https protocol, you must obtain a site certificate identifying the server upon which the interface runs that will allow for both the site authentication and encryption keys required/provided by the https protocol. Your Computrition interface support specialists can advise you on how to set up the certificate for the interface to use once you have obtained it. This section discusses features enabled when https is in use. Also see Appendix B for additional information regarding using the https protocol. When you initially surf to this URL you will see a prompt similar to Figure 2 (details of its appearance will vary depending on the web browser you are using):

Figure 2


You should have been given a username and password that you can enter into this dialog.

Once you have logged in using the dialog above, the UI will display its splash screen (Figure 3). Click the “Enter...” link to begin the interface UI.

Figure 4 shows that the interface has been configured to handle two sets of incoming and outgoing data streams. One of these sets is named (in this sample configuration) “Production Interface”, and the other “Test Interface”. These names may differ from site to site. (Many sites will have production and test interfaces configured in separate instances of the interface program, rather than both in one instance as shown here. In such cases you would browse to two separate port numbers, one for test, the other for production.) Lets click the “Production_Interface” link, which displays the screen shown in Figure 5.

Figure 3

Figure 4


Figure 5 shows a lot of interface status information in one screen, as a table. Near the top of the table is the same interface name (“Production_Interface”) that we saw on the previous page. Below that, on the left, is a set of columns with information about the input stream that is part of the production interface, and on the right is similar information for the output stream of the production interface. (In the example configuration shown here, the input stream has been named “Prod_In”, and the output stream “Prod_Out”.) In this example we can see (on the left) that the HL7 interface has (so far) received six HL7 messages. Had there been any errors encountered they would show as “Bad Messages”.

Once received, any good messages are put into a queue (for output to the database) where the output stream subsequently finds them. The output stream removes messages from the queue, processes them and forwards their contents to the Hospitality Suite database server. We can see (on the right side of Figure 5) that six messages have been removed from the queue, and that they were sent to the database server. We also see that all six of them received some kind of warning from the database, and that there were no errors. Warning or error responses that result from the processing of a message cause the interface application to format a printout and send it to a specified printer. This printout gives pertinent information about the kind of warning/error, about the particular patient to whom the message refers, date/time information, and other details that are helpful in resolving the problem. Additional information regarding these warning messages is contained in a separate document entitled “Hospitality Suite Interface: Warning and Error Messages”. For each input and output stream shown in the table (Figure 5), there is a link labeled “View stream error log”. Clicking this link will open a pop-up window (if your browser allows pop-ups) containing the stream error log. (Note that this error log is not the same as the printed error/warning messages described above.) This error log shows other information: timestamps for the stream startup or shutdown; database/client errors that prevent the stream from connecting to the database server; network connection status; other internal error conditions; other interface status changes. Also for each stream there is a link labeled “Pause”. Clicking this link allows you to toggle the stream status from running to paused and vice-versa. This is rarely used, but it can be useful during times when database maintenance is occurring. You can, for example, pause an output stream to cause it to stop sending data to the database while allowing the interface to continue to service other input and output streams. When an output stream is in a paused state any messages sent to its associated input stream are stored in the interface’s queue, and will be processed later when the paused stream is allowed to resume processing. At both the top and bottom of this table is a button labeled “Previous Page”. Clicking this button will return you to the page from which we came to this one.

Throughout the UI you will see these “Previous Page” buttons. Whenever one of these buttons appears you should always use it instead of the browser's “back” button. In some circumstances, using the browser's “back” button will not give the same result, and could cause the loss of settings changes you've made.

If your interface is configured to use the HTTPS protocol (secure HTTP), there are two additional

Figure 5


hyperlinks on the right-hand side of the table, as shown in Figure 5: “View daily printer error logs”, and “View per-patient HL7 message logs”. (If your interface is NOT configured to use the HTTPS protocol these two items will not be available.)

The link “View daily printer error logs” will, when clicked, take you to a page similar to the one shown in Figure 6. Whenever the HL7 interface creates a printout, it also logs it to disk. This screen displays of the available logged reports. You can view each day's printed logs by simply clicking on one of the green hyperlinks on this screen.

Figure 7

Clicking on the Wed_Jul_23_2008 link shown in Figure 6 will cause your browser to open a popup window similar to the one at left (Figure 7). This popup will contain copies of all the printed reports created by the interface on that date (in this case, July 23, 2008). This is an exact copy of information that was (or could have been) sent to the printer. Now, close any popup windows you may have open (Figure 7) and click the “Previous Page” button, which will return to the screen of Figure 5.

Figure 8

On the screen of Figure 5, click on the hyperlink “View per-patient HL7 message logs” which will take you to the screen shown in Figure 8. When you need to see the actual HL7 messages that the interface keeps in its logs, you can enter into this form the Medical Record Number of the patient in question, then click the button “Find Messages”. A popup window will appear (if your browser is not blocking popups) containing all the messages for that MRN that exist in the interface logs. See Figure 9.

Figure 6


Figure 9

When finished viewing this info, close the popup, returning to the screen of figure 8. Then, click the “Previous Screen” button (twice) which will return us to Figure 10 (the same as Figure 4).

The “Test_Interface” link will display details for the set of input and output streams that are configured for the test interface. We won't look at it now, as it is much the same as what we’ve just viewed. The button “PAUSE ALL INTERFACE STREAMS” is equivalent to going to each table (as we did above) and clicking both of its “Pause” buttons. Once you've clicked this button, its text changes to “UNPAUSE ALL INTERFACE STREAMS”. Using this button overrides any paused/running status that may have been previously set at the individual stream level. Clicking on “View User Interface Documentation” will attempt to use the Adobe Acrobat Reader (which is assumed to already be installed on the workstation where your web browser is being run) to display a copy of this document (the one you’re reading now) in a popup window.

Figure 10


Figure 11

When we click the “SHUT DOWN ENTIRE INTERFACE” button (in Figure 10), we see the page shown in Figure 11. You would use “RESTART” when interface configuration files have changed, to cause them to be reloaded. (You will usually be asked by a Computrition support person to do this when the need arises.) This button cannot start an interface that has been shutdown entirely. You would use “SHUTDOWN” to terminate the interface, leaving it turned off. Once it has been shut down you will not be able to connect to it with your web browser (since the interface IS the web server). To restart it you will need to enter the appropriate commands at the interface server machine. (See Figure 1 and its accompanying text, above.) The “CANCEL” button is equivalent to the “Previous Page” buttons we have already seen elsewhere. It is used to leave this page without making any changes.


Using the Text-Based UI Starting and operating the interface Follow the steps below to start the interface program: • Login on the interface server computer GUI screen as interface. (note that the

graphical login is not required, you can just as well use one of the text-mode virtual consoles on the interface server machine for this purpose, or you can use a SSH (Secure Shell) connection from another computer—such as “putty” which is available for Windows.)

• Open a text command screen (click on the screen icon at the bottom) • To start the interface type:

./HS_interface<enter>

The interface will start up and tell you to type YES when you want to exit. • Once the interface has received a message from your IS department’s server, you

will see a message on the screen about having queued 1 message as well as other status. After a moment, a message about having de-queued 1 message (see below) will appear. This represents having been able to send the message to the database and having gotten back some kind of acknowledgement. It will also indicate whether errors or warnings occurred while attempting to update the patient database. If errors/warnings have occurred and printouts are enabled and a printer is configured you should get a printout showing details of the problem.

Figure 7

Every time a new message is processed, a new set of information about queued and dequeued messages will appear. If the screen does not appear to be changing after a few minutes and you know messages are being sent, it is possible the interface is “stuck” on a message and this will need to be investigated.

• If all went successfully, you should be able to go a Hospitality Suite client and view

the patient in HS.


• To stop the HL7 interface you must go to the screen where the interface is running (that is, the one in which you started it using the directions above). Type YES and wait for the interface to terminate. To exit the command screen, type exit.


Appendix A Hospitality Suite When using Hospitality Suite, especially when using it with an interface, there are a few things that need to be maintained using the Hospitality Suite software 1. Verify that patients are being admitted, transferred and discharged properly by

routinely running and examining the Patient Report. 2. Empty the system of discharged patients. When patients are discharged by the

interface, they remain as inactive patients in the database. Over time, the number of patients can increase to an unmanageable size. To clean out the database of inactive patients, run the Discharge process by clicking on Go To > Patrons > Delete Discharged Patrons and follow prompts. Acute care facilities should run this process daily, preferably at a time when system activity is low (such as early morning hours). Long-term care facilities should run this process weekly.

For further details, please see the Computrition trainer assigned to your account.


Appendix B UI Internals The Web Server that provides the User Interface is internal to the HL7 interface. There are no external web servers in use for this product (such as the Apache or IIS web servers). The HL7 interface dynamically links to the “Swill Library”. Swill is a toolkit that can be used by other programs to expose selected internals via a Web-based interface. Swill bears the copyright notices "Copyright (C) 1998-2005 University of Chicago" and . “Copyright (C) 2005-2007 David M. Beazley.” Swill is "Free Software", and is distributed under the terms of the GNU Lesser General Public License ("The LGPL"). According to the terms of the LGPL, Computrition is providing a copy of the Swill source code and a copy of the LGPL (the license itself is contained in the file "COPYING", contained inside the Swill source code archive). Swill is used by the interface as a "shared library". Under the terms of Section 6b of the LGPL Computrition has met its obligations under the license by 1) including this written notice "prominently", 2) including the LGPL work's source code and the license in the package, and 3) displaying any copyright notices that pertain to the LGPL work at program runtime. The Swill source code archive will be placed (by the interface installation program) into a directory named "swill" as part of the interface's own directory structure. For more information about Swill, see: http://sourceforge.net/projects/swill/ Using the HTTPS protocol As of the 17.5 release of Hospitality Suite (and its accompanying HL7 interface) Swill allows HTTPS connections. When the HL7 interface is configured to use the HTTPS protocol, all traffic between a client browser and the swill server is encrypted. The password authentication mechanism used in Swill does not use encrypted storage for username/password pairs, so they are stored on the interface server in clear text. However, when using HTTPS the data stream for the entire browser session between your web browser and the HL7 interface is encrypted, so all usernames and passwords will be protected from network snooping. Access privileges to the interface server itself should be controlled, as with any other mission-critical server in your facility, to prevent unauthorized persons from logging in and modifying or accessing information stored therein. The web-based UI’s username/password mechanism is optional, and can be disabled (but Computrition strongly recommends against disabling it). If disabled, any browser that can connect to the server will be able to view pages and change settings. Computrition recommends that the HL7 interface’s Web-based UI be used only within your secure network when the HTTPS protocol is not being utilized. Note that this User Interface will expose patient information to its users only when the HTTPS protocol is being used, so there should be no HIPAA issues in its use. Note, also, that Swill is a single-threaded web server. This implies that if two or more browsers are talking to it at the same time, unexpected results may occur because of interactions between the two different browsers.

Hospitality Suite HL7 ADT/Diet Order Interface User...

Documents

Transcript of Hospitality Suite HL7 ADT/Diet Order Interface User...