Tool-Assisted Knowledge to HL7 v3 Message Translation (TAMMP) Installation Guide December 23, 2009 Richard Lyn lynrf@mcmaster.ca Jianwei Yang yangj29@mcmaster.ca
Document Revision History Rev. Level Date Description Important 2009/12/23 Initial Version Reference Documents Document # Description
1. Overview...4 1.1 Purpose...4 1.2 How to Use This Document...4 1.3 Assumptions...5 2. System Requirements...6 2.1 Hardware Requirements...6 2.2 Operating System Requirements...6 2.3 Software Requirements...6 2.4 Web Browser Requirements...7 3. Installation and Configuration...8 3.1 Apache Tomcat...8 3.2 MySQL...13 3.3 Sesame Framework...18 3.4 Testing TAMMP Tool...22
1. Overview 1.1 Purpose The integration of systems using HL7 v3 requires a large effort on the part of IT professionals to gain sufficient knowledge of the standard itself in order to perform message design tasks independently. Employing healthcare professionals to provide the necessary domain knowledge would be costly and inefficient since typically they have little IT knowledge. Further, since HL7 is an evolving standard, integrators would require constant upgrading of their knowledge in order to be productive. The complexities associated with organization of HL7 artifacts pose difficulties for non-domain expert IT professionals in identifying appropriate message structures for use during system integration. As a result message workflow design with HL7 v3 typically involves top-down analysis of the entire information model hierarchy. The tedious process of HL7 v3 based integration of systems can be improved tremendously by developing guidelines, processes and tools to support system integrators. However, to the best of our knowledge, well-defined frameworks and open-source tools supporting design and implementation of HL7 v3 based integration, are unavailable as of today. As such, message workflow design typically involves wading through pages of HL7 documentation with the help of a primitive text search alone. The Tool-Assisted knowledge to HL7 v3 Message Translation (TAMMP) will guide users through the communication design phase of healthcare integration projects. The proposed process streamlines translation of healthcare scenarios into HL7 v3 messages in a seamless manner by using the concept of structured healthcare transactions. The process consists of three stages: Integration Requirements Analysis, Structured Transaction Generation and Mapping. 1.2 How to Use This Document In this document, the first part gives the system requirements for running TAMMP. This includes the software and hardware prerequisites. The second part describes the steps to install and configure all necessary software to run TAMMP.
1.3 Assumptions In addition to the instructions outlined in this manual, it is assumed that anyone installing TAMMP should have working knowledge and/or experience with: General installation of software on the target platform Proficient use of Mac OS X operating system Administration of relational database management system (MySQL) Administration of Tomcat web application server Knowledge of Resource Description Framework (RDF) and Sesame framework
2. System Requirements System requirements for TAMMP are separated into several groups: Hardware Requirements Operating System Requirements Software Requirements Web Browser Requirements 2.1 Hardware Requirements The hardware used for TAMMP should meet the following minimum requirements: Mac computer with an Intel processor At least 1 gigabyte (GB) of RAM 92 MB hard disk space that includes 65 MB for MySQL Community server, 20 MB for Sesame Framework, 7 MB for Apache Tomcat. 9 MB hard disk space for TAMMP 2.2 Operating System Requirements TAMMP has been tested and is supported on the following operating system platforms. Mac OS X Platforms (Leopard 10.5 and Snow Leopard 10.6) 2.3 Software Requirements To install TAMMP, the following products are necessary: Latest version of MySQL Community Server Apache Tomcat 5.5 Latest version of Sesame Framework
2.4 Web Browser Requirements All functions and views of TAMMP use a standard Web browser. Presently the following browsers have been tested and supported: Firefox Browser 2.007 or greater Apple Safari 3.2.3 or greater
3. Installation and Configuration 3.1 Apache Tomcat Download Apache Tomcat 5.5 from http://tomcat.apache.org/download-55.cgi and make sure to select the Zip link from the 5.5.27 Binary Distributions Core shown in the following figure. Extract the contents of the file apache-tomcat-5.5.27.zip and place the following folder apache-tomcat-5.5.28 into the /usr/local directory. Now set permissions for the bin (/usr/local/apache-tomcat-5.5.27/bin) directory for the Tomcat server by using the following command chmod 755 *.sh in the terminal.
While still in the bin directory, start the Tomcat server by executing the command./startup.sh. A notification as shown below should be displayed and provide information that Tomcat has started:
Note: To stop the Tomcat server, while still in the bin directory, execute the command./shutdown.sh. A notification similar to starting Tomcat will be shown and provide information that Tomcat has been terminated. To confirm that the Tomcat server is working correctly, using a web browser (IE, Firefox, Google Chrome, Safari, etc.), enter in the following web address http://localhost:8080/. The following web page should be presented which indicates that Tomcat is running: To access Apache Tomcat Manager, a new username and password must be created within the tomcat-users.xml file. The tomcat-users.xml file is located within the /usr/local/apache-tomcat-5.5.27/conf directory. Using a text editor add the following line with the chosen username and password similar to figure shown below.
Now to access the Tomcat Manager, under Administration select Tomcat Manager. This will present a new window asking for a username and password. Enter the username and password that was added to the tomcat-users.xml file: The following administrative page will be presented where information about the server along with deployed running web applications:
Download the source for the TAMMP WAR file (tammp.war) from the TAMMP web site at: (WEB URL). In the Tomcat Manager under WAR file to deploy select the browse button and locate the HL7ToolV2.war file then select Deploy to add the TAMMP tool to the Tomcat server. This will extract all files from the WAR file and enable the TAMMP tool for use. Library file (JAR files) are required for TAMMP to operate properly. Copy all JAR files within the lib directory to the lib directory located at /usr/local/apache-tomcat-5.5.27/webapps/hl7toolv2/web-inf/. Overwrite any duplicated files. The HL7 V3 ballot is required for the TAMMP tool to operate properly. Download the ZIP (v3ballot_fullsite_2010jan.zip) file containing the HL7 V3 ballot from the TAMMP web site at: (WEB URL). Create a new directory called hl7 within the webapps directory located at /usr/local/apache-tomcat-5.5.27. Extract the ZIP file and copy the contents to the hl7 directory. Download the XML file hl7.xml from the TAMMP web site at: (WEB URL) and copy the file to the localhost directory located at /usr/local/apache-tomcat-5.5.27/conf/catalina.
3.2 MySQL MySQL is a relational database management system (DBMS) that is required for the TAMMP tool to operate properly. Download the latest version of MySQL Community Server from http://dev.mysql.com/downloads/: Select the Download button that will provide links for MySQL based on operating system. Make sure to select the Mac OS X (Package Format) platform and download the Mac OS X 10.x (x86) depending on which version of OS X: Execute file mysql-x.x.xx-osx10.4-x86.dmg or mysql-x.x.xx-osx10.5-x86.dmg (x represents the version number) and execute all the files in the package shown below.
Now download the latest MySQL GUI Tools for OS X from http://dev.mysql.com/downloads/gui-tools/ which include: MySQL Administrator MySQL Query Browser MySQL Migration Toolkit Download and Execute file mysql-gui-tools-5.0-r12-osx10.4-universal.dmg. Copy the MySQL Tools folder into the Applications folder.
In order for the Sesame Framework to access the MySQL database the correct password must be set for the root user. Start the MySQL Administrator located in the Applications folder.
Confirm that the username is root and password is admin and connect to the database. Select the Accounts tab and then the root account. Change the Password field to sesame and confirm the password then save the changes.
Now start the MySQL Query Browser located in the Applications folder. Make sure the username is set to root and the password is sesame. From the navigation window on the right-hand side, select and right click def and select Create Schema.
Call the new schema hl7store and repeat the process and name the next schema tammpstore. Select the tammpstore schema by double clicking the database in the navigation menu on the right-hand side. From the menu bar, select open script and load tammpstore.sql. A SQL script will be displayed, execute it by selecting the execute (green lightning bolt). 3.3 Sesame Framework Sesame Framework is an open-source RDF framework with support for RDF schema inferencing and querying. It will be used to implement a RDF repository by leveraging a MySQL database. Download Sesame 2.3.0 ZIP file from http://www.openrdf.org/download.jsp: Extract the ZIP file openrdf-sesame-2.3.0-sdk.zip. Using the Tomcat Manager as described in section 3.1, under WAR file to deploy select the browse button and locate within the openrdf-sesame-2.3.0/war directory the openrdf-sesame.war and openrdf-workbench.war file. Deploy each WAR file to add to the Tomcat server. This
will extract all files from the WAR file and enable Sesame for use. To confirm that Sesame is working correctly, using a web browser (IE, Firefox, Google Chrome, Safari, etc.), enter in the following web address http://localhost:8080/openrdf-sesame. The following web page should be presented which indicates that Sesame is running: To confirm that Sesame Workbench is working correctly, using a web browser (IE, Firefox, Google Chrome, Safari, etc.), enter in the following web address http://localhost:8080/openrdf-workbench. The following web page should be presented which indicates that Sesame Workbench is running: A new RDF repository will be setup utilizing the hl7store MySQL database. In the Sesame Workbench, select Add Repository from the menu on the left-hand side. Under Type, select MySql RDF Store, ID enter HL7Store and Title enter RDF Repository.
After clicking Next, information about the database that will be used for the RDF repository need to be completed. Under Database enter hl7store, User Name enter root and Password enter sesame Click Create to finish. To verify that the new RDF repository has been correctly added, select Repositories from the menu on the left-hand side. A new RDF repository will now be listed.
Now the interactions must be loaded into the RDF repository. Download the RDF XML file tammp-interactions from the TAMMP website at: (WEB URL). In the Sesame workbench, within the Modify section, select Add from the menu on the left-hand side. Uploading of the interactions can be done either by a text file or by writing the RDF XML in the textbox provided. If upload by text file, select the radio box Select the file containing the RDF data you wish to upload then select Choose File and browse to file the RDF XML text file tamp-interactions. Finally select Upload to add the RDF interactions. If upload is by inputting the RDF XML then select the radio box Enter the RDF data you wish to upload then copy and paste the text into the textbox provided. Finally select Upload to add the RDF interactions.
3.4 Testing TAMMP Tool To test that TAMMP is available and working, make sure that Tomcat is online and running. In a web browser (IE, Firefox, Safari, etc.) enter the following URL http://localhost:8080/hl7toolv2. The following web page should be presented to allow a storyboard narrative to be entered. Congratulations TAMMP has been installed and configured correctly. --------- End ---------