CONNECT Vangent Health Information Exchange Open Source (HIEOS) Document Registry and Repository Installation and Configuration Manual

Transcription

1 CONNECT Vangent Health Information Exchange Open Source (HIEOS) Document Registry and Repository Installation and Configuration Manual Version 1.0 CONNECT Release September 2009

2 REVISION HISTORY REVISION DATE DESCRIPTION September 2009 Initial Release CONNECT_Vangent_HIEOS_Manual i Release 2.2

3 TABLE OF CONTENTS 1.0 INTRODUCTION PURPOSE SCOPE DOCUMENT DESCRIPTION REFERENCED DOCUMENTS INSTALLATION AND CONFIGURATION CHECKLIST ENVIRONMENT FOOTPRINT HARDWARE REQUIREMENTS FOR INSTALLATION SOFTWARE REQUIREMENTS FOR INSTALLATION OBTAIN MEDIA/ SOFTWARE UNZIP THE NHIN CONNECT GATEWAY FILE INSTALLATION AND CONFIGURATION INSTRUCTIONS CHANGE THE METADATA CODES THAT ARE VALIDATED BY THE VANGENT REPOSITORY CHANGE OTHER VANGENT CONFIGURATION ITEMS VALIDATE AND TEST THE VANGENT DEPLOYMENT CONFIGURE CONNECT TEST THE VANGENT-CONNECT CONFIGURATION ACRONYMS...14 CONNECT_Vangent_HIEOS_Manual ii Release 2.2

4 1.0 INTRODUCTION 1.1 Purpose This document is the installation and configuration manual for installing the Vangent Health Information Exchange Open Source (HIEOS) Document Registry and Repository software in either a Windows or Solaris environment. This document includes the process for installing the Vangent HIEOS Document Registry and Repository software on a separate server but in conjunction with the NHIN CONNECT Gateway and Adapter software. The Vangent HIEOS software can be installed on the same server as the CONNECT software, but there are additional steps that need to be taken to avoid certain file contentions. For the purpose of this document, a separate server installation is assumed and recommended. The Vangent HIEOS Registry and Repository software is the chosen NHIN CONNECT document registry and repository components for enterprise-type installations for this release of NHIN CONNECT. 1.2 Scope The procedures referred to in this document are applicable to all CONNECT users running either a Windows or Solaris environment. 1.3 Document Description This document includes the following sections: Section 1.0 Introduction Section 2.0 Referenced Documents Section 3.0 Installation and Configuration Checklist Section 4.0 Environment Footprint Section 5.0 Obtain Media/Software Section 6.0 Installation and Configuration Instructions Section 7.0 Validate and Test the Vangent Deployment Section 8.0 Configure CONNECT Section 9.0 Test the Vangent CONNECT Configuration Section 10.0 Acronyms 2.0 REFERENCED DOCUMENTS n/a CONNECT_Vangent_HIEOS_Manual 1 Release 2.2

5 3.0 INSTALLATION AND CONFIGURATION CHECKLIST Item Procedural Step Download Vangent software binary files Set up Database Set up Application server Set up IDE (optional) Set up Environment variables Deploy software Validate and Test the deployment Configure CONNECT Test the CONNECT-Vangent configuration 4.0 ENVIRONMENT FOOTPRINT 4.1 Hardware Requirements for Installation This section describes the recommended minimum hardware component infrastructure, including processor performance, disk space, and RAM for the application server platform. This information is subject to change based on continued development. This information mirrors the hardware requirements for CONNECT Release 2.2 and is repeated here for your convenience. Item Version 2.0 Processor Minimum dual 2GHz CPU RAM Minimum of 4 GB Hard Disk Size Application Dependent on the deployment configuration. For sizing purposes, assume 100K per CCD record, 1K per audit log record. Hard Disk Speed Minimum of 7200 RPM and RPM preferred. Network Interface 100MB Ethernet acceptable; 1GB Ethernet desirable CONNECT_Vangent_HIEOS_Manual 2 Release 2.2

6 4.2 Software Requirements for Installation This section describes dependent software products. Item Description Operating System Windows Server 2003 and above or Sun Solaris 10 Sparc 64 bit Java-JRE/JDK Java SDK 1.6 Update 13, Build 3 Application Servers GlassFish v2.1 Communication Stack Axis2 v1.4.1 Network Protocol TCP/IP Relational Database MySQL v5.1 Recommended Test Tools (Optional) soapui v2.5.1 CONNECT_Vangent_HIEOS_Manual 3 Release 2.2

7 5.0 OBTAIN MEDIA/ SOFTWARE Download the Vangent HIEOS component packages from the CONNECT Site. Step Action Input Expected Result 1 WINDOWS: Download the Vangent_HIEOS_Registry_Repositor y_mmddyyyy.zip file from the NHIN CONNECT release site. The file is now located on your computer. SOLARIS: Download the Vangent_HIEOS_Registry_Repositor y_sol10_ tar.gz file from the NHIN CONNECT release site. 5.1 Unzip the NHIN CONNECT Gateway File Step Action Input Expected Result 1 WINDOWS Unzip the Vangent_HIEOS_Registry_Repositor y_mmddyyyy.zip file downloaded from the NHIN CONNECT release site. It should uncompress into the directory chosen by the installer. SOLARIS Untar the file downloaded to your $Home path and this should untar the content to $HOME/Vangent path 6.0 INSTALLATION AND CONFIGURATION INSTRUCTIONS The Vangent HIEOS software can be installed on the same server as the CONNECT software but there are additional steps that need to be taken to avoid certain file contentions. For the purpose of this document, a separate server installation is assumed and recommended. Please refer to the following link on the Vangent website for Vangent HIEOS installation and configuration instructions and follow the setup path for the MySQL configuration with the installation variances noted below: CONNECT_Vangent_HIEOS_Manual 4 Release 2.2

8 Installation Variances: The installer should not check-out or build the Vangent software source code as mentioned in the setup instructions found at the link above. The Vangent Repository code has been slightly modified to work with the CONNECT software and will be contained in the Vangent_HIEOS_Registry_Repository_mmddyyyy.zip/ Vangent_HIEOS_Registry_Repository_mmddyyyy.tar.gz (for Solaris) file. The files in this zip file will already contain most of the files referenced in the Deployment Steps section with the exception of the xds.aar and xca.aar files. These files are included in the axis2.war file contained in the before mentioned zip file. Use the MySQL database scripts found in the above mentioned zip file under the data directory of that zip/tar file. Since the installer does not need to download the source code which contains the database scripts needed to create the Vangent repository tables, these scripts have been included in the zip/tar file which were downloaded earlier. Note: For Solaris installations, the omar schema table names are lowercase, but the Java Code may refer to these tables using some uppercase letters. For example, you might get an exception stating that the omar.externalidentifier table is not found. In this instance, you would modify the table name to omar.externalidentifier so that the table can be recognized. Consequently, you may need to modify all of the table names to avoid these inconsistencies. The installer should not download the axis2.war file from the Apache web site. This war file has been modified to include the pre-compiled xds.aar and xca.aar files for the Vangent repository. The axis2.war file should be copied to the «AS_HOME»\domains\domain1\autodeploy directory as indicated in the Vangent instructions. Use the JDBC driver from the zip file, mysql-connector-java bin.jar, during the Connection Pool Configuration setup section in the Vangent install guide. The JDBC driver referenced in the Vangent instructions are contained in the Vangent source code and has been included in the zip/tar file you downloaded earlier from the CONNECT web site. Environment variables: You can use the codes.xml and xconfig.xml files found in the zip file you downloaded earlier from the CONNECT web site for the HIEOSxCodesFile and HIEOSxConfigFile environment variables. These two variables are required to run the Vangent repository. When running the verification process addressed later in this document, you will also need to set the HIEOSxTestDir and HIEOSxLogDir environment variables. You can set the HIEOSxTestDir variable to point to the hieos\src\xtest\test\ directory as extracted from the Vangent_HIEOS_Registry_Repository_mmddyyyy.zip file. The HIEOSxSchemaDir environment variable does not need to be set and the Vangent software will use a default setting. CONNECT_Vangent_HIEOS_Manual 5 Release 2.2

9 Setting classpath is an important step in the Solaris environment. After setting the environment variables, edit the classpath file under the Vangent installation directory $HOME/Vangent/hieos/src/xtest/test. The integration of NetBeans with GlassFish and Axis2 as referenced in the Vangent installation guide is optional. All of the war and ear files contained in the zip file mentioned above can be copied to the «AS_HOME»\domains\domain1\autodeploy directory instead of deploying them through NetBeans. The TLS Configuration section of the Vangent setup guide has not been tested with this release of CONNECT. 6.1 Change the Metadata Codes that are Validated by the Vangent Repository The Vangent Repository software will validate certain metadata values using a file called codes.xml. This file, after the Vangent software has been deployed into GlassFish, should be located at: <<AS_HOME>>\domains\domain1\generated\xml\j2ee-modules\xref\codes\codes.xml The codes.xml file located above will not be used if the HIEOSxCodesFile environment variable has been set. If changes need to be made to the codes validated by the Vangent repository, make those changes to the codes.xml file that is pointed to by the HIEOSxCodesFile environment variable. Some of the codes used with NHIN have been included in a codes.xml file included in the zip file you downloaded in section 5.0. You may use this file in place of the existing codes.xml file or you may choose to simply edit the original file with the needed codes. As additional NHIN codes or the needs of your organization change such that new codes need to be added or existing codes need to be modified, the following steps outline how this may be accomplished. The NHIN confidentiality class code metadata item is being used in the steps below to illustrate where to go to modify this code should it ever need to change. 1. Open the codes.xml file in your preferred text editor. 2. Locate the confidentialitycode metadata item. 3. Add the following text to the bottom of this section. 4. <Code code="r" display="restricted" codingscheme=" "/> 5. Note: you may also simply edit the codingscheme attribute to match the codingscheme value above if the Restricted confidentiality code already exists in this file. 6. Save the file. CONNECT_Vangent_HIEOS_Manual 6 Release 2.2

10 6.2 Change other Vangent Configuration Items Other configuration items may be altered for your Vangent installation. For a more complete description and list of these items, please see the Vangent/HIEOS configuration web page at the following web address: This web page was already referenced on the Vangent setup web page; however, you may need to modify your Vangent configuration further for your particular installation. This may be accomplished by editing the xconfig.xml file located (after your installation) at: <<AS_HOME>>\domains\domain1\generated\xml\j2ee-modules\xref\config\xconfig.xml The xconfig.xml file located above will not be used if the HIEOSxConfigFile environment variable has been set. If changes need to be made to your Vangent repository installation, make those changes to the xconfig.xml file that is pointed to by the HIEOSxConfigFile environment variable. An example xconfig.xml file is included in the zip file referenced in section 5.0. Some of the configuration items you may wish to modify are: HomeCommunityId ValidatePatientId validates patient ids stored in the Vangent adt database. When running the Vangent test tool (see section 7) you will need to set this value to true. When configuring for CONNECT, you will need to set this property to false. LogEnabled enables log entries to be written in the Vangent log database. For this release of CONNECT, you should set this value to false. <Property name="logenabled">false</property> CodesLocation validate that it points to the URL of your Vangent installation paying particular attention to the port value (e.g., AssigningAuthority - you may wish to add an entry for your particular organization s assigning authority patterned from the example xconfig.xml file included in the zip file referred to in section 5.0. Localregistry verify that the URL endpoints in this section correspond to your Vangent installation paying particular attention to the port value (e.g., Localrepository you may wish to change the value of the UniqueId sub-element to match your organization s pre-determined repository unique id. Also, verify that the URL endpoints in this section correspond to your Vangent installation paying particular attention to the port value (e.g., The example below shows a repository unique id or 1. <Repository name="localrepository"> <UniqueId>1</UniqueId> CONNECT_Vangent_HIEOS_Manual 7 Release 2.2

11 7.0 VALIDATE AND TEST THE VANGENT DEPLOYMENT The Vangent repository installation can be validated using the steps outlined at the following location: You can use the Vangent test software contained in the zip/tar file you downloaded earlier from the CONNECT web site. It is located under the hieos directory. You will need to modify the actors.xml file to add an entry for the repository unique id you entered in section 6.2 for the localrepository entry in the xconfig.xml file. 1. Open the <HIEOSxTestDir>\actors.xml file using your preferred text editor. 2. Search for the text, <site name="dev">. 3. Look for the <repository> XML sub-element. 4. Add a repository sub-element for the repository unique id you entered in section 6.2 above using the example below as a guide (which uses the example repository unique id value of 1 from section 6.2 above). <repository uid="1"> 5. Save the file. Remember to also set the ValidatePatientId property to true in the xconfig.xml file when using the Vangent xtest tool as indicated in section 6.2 above. <Property name="validatepatientid">true</property> CONNECT_Vangent_HIEOS_Manual 8 Release 2.2

12 The recommended set of validation tests that should be run are the Vangent test suite and test plan described below: Validation Test Description Vangent Test #11890 Basic general test that will load some test data into the document registry. Vangent Test #vsmallpnr Runs a small provide and register document set transaction test. Vangent Test #v_xds Vangent Test #12021 Test suite: v_xds Runs several tests at the same time. Test plan: 1. Includes test cases that submit a document to the repository, 2. Executes a query for that document, and 3. Retrieves that same document. NOTE: On Solaris you might have to set the executable permissions to xtest file. 8.0 CONFIGURE CONNECT 1. Ensure the AdaptersDocRepository2Soap12EJB EJB component has been deployed into glassfish. 2. Modify the adapterxdsbdocrepository service entries in the internalconnectioninfo.xml file to point to the endpoint reference serviced by the AdaptersDocRepository2Soap12EJB component as in the following example: <service> <name>adapterxdsbdocrepository</name> <description>adapter Document Retrieve</description> <endpointurl> rdocrepository2soap12service</endpointurl> CONNECT_Vangent_HIEOS_Manual 9 Release 2.2

13 </service> 3. Modify the adapterxdsbdocregistry service entries in the internalconnectioninfo.xml file to point to the endpoint reference serviced by the new Vangent/HIEOS repository as in the following example: <service> <name>adapterxdsbdocregistry</name> <description>adapter Document Query</description> <endpointurl> </service> 4. Modify the adapterxdsbdocrepositorysoap12 service entries in the internalconnectioninfo.xml file to point to the endpoint reference serviced by the newly installed Vangent repository as in the following example: <service> <name>adapterxdsbdocrepositorysoap12</name> <description>adapter Document Retrieve Soap12</description> <endpointurl> L> </service> 5. Modify the Vangent xconfig.xml file (see section 7.0 above) to set the ValidatePatientId property to false. <Property name="validatepatientid">false</property> 9.0 TEST THE VANGENT-CONNECT CONFIGURATION The Vangent-CONNECT configuration may be tested using the CONNECT Internal Self Test suite that was used to test the installation of the CONNECT software with a few modifications to the test suite. Listed below are the changes to the procedure that the installer will need to follow after testing the basic CONNECT software. Please note that these changes are based on the Vangent test plan # The actual values used will most likely not be the same as the ones listed below. The installer will need to use the actual values received in the Vangent test log files. 1. Open the InternalSelfTest.properties file in your preferred text editor. 2. Open the Vangent xtest log file (log.xml) for the query test case for test plan # This file should be located using the HIEOSxLogDir environment variable that was set as part of the Vangent installation from section 6.0 above. There will be a log.xml file for each test case in the test plan which will be stored according to the test number and test case. The following are some examples: <HIEOSxLogDir >\tests\12021\query\log.xml for the query test case for test plan # CONNECT_Vangent_HIEOS_Manual 10 Release 2.2

14 <HIEOSxLogDir >\tests\12021\submit\log.xml for the submit test case for test plan #12021 <HIEOSxLogDir >\tests\12021\retrieve\log.xml for the retrieve test case for test plan # Modify the LocalAA property in the InternalSelfTest.properties file with the same assigning authority used earlier to store the test document in the Vangent repository, as shown below: LocalAA= This assigning authority value can be found by searching the <HIEOSxLogDir >\tests\12021\query\log.xml file for the text, XDSDocumentEntry.patientId, and then using the XML attribute value value from the XML element, ExternalIdentifier. The assigning authority value in the log file will be part of the patient identifier and is highlighted in the example below. <ns1:externalidentifier identificationscheme="urn:uuid:58a6f841-87b3-4a3e-92fda8ffeff98427" registryobject="urn:uuid:ca08c166-ed bede-d821f568732f" value="4076bd3ffd6b44d^^^& &iso" lid="urn:uuid:39bf110c-2e77-46f3-98b0-2411cd5805b0" objecttype="urn:oasis:names:tc:ebxmlregrep:objecttype:registryobject:externalidentifier" status="urn:oasis:names:tc:ebxml-regrep:statustype:submitted" id="urn:uuid:39bf110c-2e77-46f3-98b0-2411cd5805b0"> <ns1:name> <ns1:localizedstring charset="utf-8" value="xdsdocumententry.patientid" xml:lang="en-us" /> </ns1:name> <ns1:description /> <ns1:versioninfo versionname="1.1" /> </ns1:externalidentifier> 4. Under the Document Query data section of the InternalSelfTest.properties file, modify the DQPatientID property to match the patient id that was used to test the Vangent repository as shown below (see section 7.0): # Document Query data DQDocID= #DQPatientID=D DQPatientID=4076bd3ffd6b44d Using the xtest test plan #12021 as an example, use the log.xml file from the query test case noted in the above step to locate the patient id value that is listed before the assigning authority value. The patient id value is highlighted in the example below. <ns1:externalidentifier identificationscheme="urn:uuid:58a6f841-87b3-4a3e-92fda8ffeff98427" registryobject="urn:uuid:ca08c166-ed bede-d821f568732f" value="4076bd3ffd6b44d^^^& &iso" CONNECT_Vangent_HIEOS_Manual 11 Release 2.2

15 lid="urn:uuid:39bf110c-2e77-46f3-98b0-2411cd5805b0" objecttype="urn:oasis:names:tc:ebxmlregrep:objecttype:registryobject:externalidentifier" status="urn:oasis:names:tc:ebxml-regrep:statustype:submitted" id="urn:uuid:39bf110c-2e77-46f3-98b0-2411cd5805b0"> <ns1:name> <ns1:localizedstring charset="utf-8" value="xdsdocumententry.patientid" xml:lang="en-us" /> </ns1:name> <ns1:description /> <ns1:versioninfo versionname="1.1" /> </ns1:externalidentifier> 5. Under the Document Query data section of the InternSelfTest.properties file, modify the DQDocID property to match the document id that was used to test the Vangent repository as shown below (see section 7.0): # Document Query data # DQDocID= DQDocID= #DQPatientID=D DQPatientID=4076bd3ffd6b44d The document id can be located by searching for the XDSDocumentEntry.uniqueId text value in the same log.xml file referenced in the previous steps in this section. This text corresponds to the XML element, ExternalIdentifier for a document. The value attribute contains the document id needed as highlighted in the example below. <ns1:externalidentifier identificationscheme="urn:uuid:2e82c1f6-a085-4c72-9da3-8640a32e42ab" registryobject="urn:uuid:ca08c166-ed bede-d821f568732f" value=" " lid="urn:uuid: b-4ffc-4ce f3f46e6b89ec" objecttype="urn:oasis:names:tc:ebxmlregrep:objecttype:registryobject:externalidentifier" status="urn:oasis:names:tc:ebxml-regrep:statustype:submitted" id="urn:uuid: b-4ffc-4ce f3f46e6b89ec"> <ns1:name> <ns1:localizedstring charset="utf-8" value="xdsdocumententry.uniqueid" xml:lang="en-us" /> </ns1:name> <ns1:description /> <ns1:versioninfo versionname="1.1" /> </ns1:externalidentifier> CONNECT_Vangent_HIEOS_Manual 12 Release 2.2

16 6. Under the Document Retrieve data section of that same InternalSelfTest.properties file, modify the DRDocID property to match the document unique id that was used to test the Vangent repository (see section 7.0). This value should also be the same document id used in the previous step, similar to the following example: # Document Retrieve data #DRDocID= DRDocID= DRRepoID=1 7. Save the file. 8. Open the InternalSelfTest project in soapui and run the docquery and docretrieve self tests. These tests should pass using the documents found in the Vangent repository stored earlier. CONNECT_Vangent_HIEOS_Manual 13 Release 2.2

17 10.0 ACRONYMS CA CAC CD CDC CMS DAT DOD DURSA DVD EHR EMR ESB FHA GB HDD HIEOS HITSP IDE IHS Certificate Authority or Composite Application depending on the context. Common Access Card Compact Disk Centers for Disease Control & Prevention Centers for Medicare & Medicaid Services Digital Audio Tape Department of Defense Data Use and Reciprocal Support Agreement Digital Video Disc Electronic Health Record Electronic Medical Record Enterprise Service Bus Federal Health Architecture Gigabyte Hard Disk Drive Health Information Exchange Open Source Healthcare Information Technology Standards Panel Integrated Drive Electronics Indian Health Services IPv6 Internet Protocol Version 6 MB MPI NCI NDMS NHIE NHIN NIST OID ONC Megabyte Master Patient Index National Cancer Institute National Disaster Medical System NHIN Health Information Exchange Nationwide Health Information Network National Institute of Standards and Technology Object Identifier or Home Community ID Office of the National Coordinator CONNECT_Vangent_HIEOS_Manual 14 Release 2.2

18 OS QA RAID RAM SCSI SDK SSA SSL TBD USB VA XDS Operating System Quality Assurance Redundant Array of Inexpensive Disks Random Access Memory Small Computer System Interface Software Development Kit Social Security Administration Secure Sockets Layer To Be Determined Universal Serial Bus Department of Veterans Affairs Cross Document Sharing CONNECT_Vangent_HIEOS_Manual 15 Release 2.2