connect solaris release 2 1 system installation and...

CONNECT Solaris Full Binary System Installation and Configuration Manual

Version 1.0

CONNECT Release 2.1

07 July 2009

CONNECT_Solaris_Full_Binary_Manual i Release 2.1 7/7/09

REVISION HISTORY

REVISION DATE DESCRIPTION

- 13 May 2009 Initial Release

- 15 May 2009 Update to include instructions to enable additional logging. Also added comment for know WARNING for Name Value Pairs messages.

1.0 7 July 2009 Updated to reflect Release 2.1

CONNECT_Solaris_Full_Binary_Manual ii Release 2.1 7/7/09

TABLE OF CONTENTS

1.0 INTRODUCTION.............................................................................................................1 1.1 PURPOSE ......................................................................................................................1 1.2 SCOPE ..........................................................................................................................1 1.3 DOCUMENT DESCRIPTION ...............................................................................................1

2.0 REFERENCED DOCUMENTS........................................................................................1 3.0 CONNECT INSTALLATION CHECKLIST ......................................................................1

3.1 INSTALLATION AND CONFIGURATION CHECKLIST ...............................................................3 4.0 OID REQUEST SUBMITTAL PROCESS........................................................................3 5.0 TEST DEPLOYMENT FOOTPRINT................................................................................4

5.1 HARDWARE REQUIREMENTS............................................................................................4 5.2 SOFTWARE REQUIREMENTS ............................................................................................4 5.3 FEDERAL GATEWAY INTERFACE (WSDL) PORTS ..............................................................5

6.0 SOLARIS INSTALL AND CONFIGURATION INSTRUCTIONS....................................8 6.1 INSTALL PREREQUISITE SOFTWARE ON SOLARIS ...............................................................8 6.1.1 JDK INSTALLATION .........................................................................................................8 6.1.2 GLASSFISHESB INSTALLATION........................................................................................8 6.2 CONFIGURATION...........................................................................................................13 6.2.1 UPDATE PROPERTY/CONFIGURATION FILE SETTINGS ......................................................16 6.2.1.1 GATEWAY.PROPERTIES .............................................................................................16 6.3 THIRD PARTY COMPONENTS .........................................................................................16 6.3.1 COMPONENT CATALOG .................................................................................................16 6.3.2 INSTALLATION OF THIRD PARTY COMPONENTS................................................................20 6.3.2.1 INSTALLATION OF GNU TAR.......................................................................................20 6.3.2.2 INSTALLATION OF LIBICONV LIBRARIES.........................................................................21 6.3.2.3 INSTALLATION OF LIBINT LIBRARIES .............................................................................21 6.3.2.4 INSTALLATION OF GCC-3.4.6 LIBRARIES ....................................................................22 6.3.2.5 INSTALLATION OF LOG4J............................................................................................22 6.3.2.6 INSTALLATION OF COMMONS LOGGING .......................................................................22 6.3.2.7 INSTALLATION OF C3P0..............................................................................................23 6.3.2.8 INSTALLATION OF HIBERNATE.....................................................................................23 6.3.2.9 INSTALLATION OF COPYV3..........................................................................................23 6.3.2.10 INSTALLATION OF METRO...........................................................................................25 6.3.2.11 INSTALLATION OF CONNECTOR/J FOR MYSQL ............................................................25 6.3.2.12 INSTALLATION OF XSTREAM.......................................................................................25 6.3.2.13 INSTALLATION OF SPRING FRAMEWORK ......................................................................25 6.3.2.14 INSTALLATION OF SOAPUI ..........................................................................................26 6.3.3 CONFIGURE THIRD PARTY COMPONENTS IN GLASSFISH ..................................................26 6.4 INSTALL AND CONFIGURE MYSQL .................................................................................27 6.4.1 INSTALLATION ..............................................................................................................27 6.4.2 STARTING AND STOPPING MYSQL.................................................................................27 6.4.3 CONFIGURING MYSQL .................................................................................................28

CONNECT_Solaris_Full_Binary_Manual iii Release 2.1 7/7/09

7.0 SSL CERTIFICATE REQUEST AND INSTALLATION PROCESS .............................29 7.1 SETUP.........................................................................................................................30 7.2 GENERATE CERTIFICATE REQUEST................................................................................30 7.3 DOWNLOAD ROOT CERTIFICATE ....................................................................................31 7.4 SEND CERTIFICATE REQUEST ........................................................................................31 7.5 INSTALL THE CERTIFICATE .............................................................................................31

8.0 NHIN-CONNECT SERVER CONFIGURATION...........................................................33 8.1 CONFIGURATION SETTINGS ...........................................................................................34 8.1.1 METRO 1.4 INSTALLATION SETTINGS..............................................................................34 8.1.2 GLASSFISH APPLICATION VARIABLES .............................................................................34 8.2 CONNECTION MANAGEMENT..........................................................................................35 8.2.1 INTERNALCONNECTIONINFO.XML FILE ............................................................................36 8.3 REIDENTIFICATION.XML .................................................................................................38 8.4 GATEWAY PROPERTIES.................................................................................................38 8.5 ADAPTER PROPERTIES .................................................................................................41 8.6 CONNECTION EPR PROPERTIES....................................................................................41 8.7 COMPONENT PROXY SPRING CONFIGURATION PROPERTIES.............................................41 8.8 HIEM TOPIC CONFIGURATION PROPERTIES ...................................................................42

9.0 DEPLOYMENT.............................................................................................................42 9.1 DEPLOYING APPLICATIONS TO GLASSFISH ......................................................................43 9.1.1 ADAPTER COMPONENTS. ..............................................................................................43 9.1.2 GATEWAY COMPONENTS ..............................................................................................43 9.1.3 UPDATE GLASSFISH LIB.................................................................................................45 9.1.4 DEPLOYMENT OF CONNECT........................................................................................46 9.1.4.1 DEPLOYMENT OF THE ADAPTER AND GATEWAY TO SINGLE MACHINE ............................46 9.2 CONFIGURATION FILES .................................................................................................46

10.0 ACRONYMS.................................................................................................................48 A. OID REQUEST SUBMITTAL PROCESS ....................................................................... A-2

A.1 GETTING STARTED ..................................................................................................... A-2 A.2 SUBMITTING THE REQUEST ......................................................................................... A-2 A.3 SEARCHING FOR AN OID ON THE SITE .......................................................................... A-8

CONNECT_Solaris_Full_Binary_Manual iv Release 2.1 7/7/09

LIST OF FIGURES

Figure 6.1-1: Glassfish Welcome Screen ..............................................................................9 Figure 6.1-2: Glassfish License Agreement........................................................................10 Figure 6.1-3: NetBeans Screen ............................................................................................11 Figure 6.1-4: Glassfish Screen.............................................................................................12 Figure 8.1-1: Manage Application Variables .......................................................................35 Figure A.2-1: HL7-OID Registration Home Page................................................................ A-2 Figure A.2-2: Complete Contact Information .................................................................... A-3 Figure A.2-3: Select type of OID......................................................................................... A-4 Figure A.2-4: New or Existing OID Designation................................................................ A-5 Figure A.2-5: HL7 OID Description..................................................................................... A-5 Figure A.2-6: OID Registration Confirmation.................................................................... A-6 Figure A.2-7: OID Email Confirmation ............................................................................... A-6 Figure A.3-1: Searching by OID number ........................................................................... A-8 Figure A.3-2: Search by OID Description .......................................................................... A-9

CONNECT_Solaris_Full_Binary_Manual 1 Release 2.1 7/7/09

1.0 INTRODUCTION

1.1 Purpose This document is the installation and configuration manual for installing the Full Binary installation of the CONNECT software on the Solaris Operating Systems. This document targets the installation and configuration of the Core Gateway components. A follow-up release of this document will target the Enterprise Level Components of the CONNECT software (OpenSSO, Jericho, NIST Repository and Mural). Some components required during the installation and configuration of the CONNECT software require privileged access to the target machine. The recommended configuration for Solaris is to create a separate partition for the installation and configuration of the third-party products used by the CONNECT gateway. For the purposes of this installation manual, that partition is named /nhin. The privileged account can be the root or another account that has the required privilege for the successful execution of the pkgadd command. If the target machine already has GNU tar installed, no privileged access is required.

1.2 Scope The procedures in this document are applicable to all CONNECT users running the Solaris Operating System.

1.3 Document Description This document includes the following sections:

• Section 1.0 Introduction • Section 2.0 Referenced Documents • Section 3.0 CONNECT Installation Checklist • Section 4.0 OID Request Submittal Process • Section 5.0 Test Deployment Footprint • Section 6.0 Solaris Install and Configuration Instructions • Section 7.0 SSL Certificate Request and Installation Process • Section 8.0 NHIN-CONNECT Server Configuration • Section 9.0 Deployment • Section 10.0 Acronyms

2.0 REFERENCED DOCUMENTS N/A

3.0 CONNECT INSTALLATION CHECKLIST The following is a workflow/checklist that guides the reader through the steps required to join the Nationwide Health Information Network (NHIN) using the CONNECT Gateway. This document is organized to follow the flow of the workflow/checklist below.


Ensure to secure hardware that meets the hardware and software requirements provided for the appropriate platform.

Select an installation method: Manual, install from a zip or install a VM Gateway image.

As applicable, download the Gateway VM software, Gateway Software zip or tar file

Follow the installation instructions for zip or tar as appropriate.

Instructions on how to request and install the SSL the CONNECT gateway.

Step to be executed by

Agency

Step executed by Agency & CONNECT

Team

Step executed by Agency &

CSC

Configure the Gateway

Obtain Media/

Software

Perform Installation

Request and Install SSL

Configure the specific gateway properties depending the Agency’s needs and platform selected

Submit a request for an OID for each gateway being configured.

Determine Installation

Method

Assess Hardware

Requirements

OID Request Process


3.1 Installation and Configuration Checklist

Item Procedural Step Download and install JDK 1.6.0_13. This is the version that the

current NHIN CONNECT Gateway was developed against and the recommended version. See section 6.1.1.

Download and install GlassFishESB, v2.1. This is available from the CONNECT Portal. See section 6.1.2.

Download, install and configuration of MySQL database. This is available from the CONNECT Portal. See section 6.4.

Download and install log4j logging components. The NHIN CONNECT Gateway used log4j for logging and debugging purposed. If issues should occur on a deployed Gateway, these log files are critical in determining the issue and seeking resolution. This is available from the CONNECT Portal. See section 6.3.2.5.

Download and install soapUI test suite. The NHIN CONNECT Gateway is deployed with a test suite to verify the installation. These tests were generated using soapUI. This is available from the CONNECT Portal. See section 6.3.2.14.

Install Third-party component libraries and jars into $AS_HOME/lib. See section 6.3.3.

Install and configure Metro 1.4 This is available from the CONNECT Portal. See section 8.1.1.

Obtain certificates from the Certificate Authority. Configure 2-way SSL using the production certificates received. See section 7.0.

Define environment variables used during deployment. See section 8.0.

Deploy NHIN CONNECT Gateway using the Glassfish Admin Console, deploy each of the Composite Applications within Glassfish. See section 9.1.

Configure the NHIN CONNECT Environment including updates to properties files. The properties files are used to customize installation for each specific install. See section 8.0.

Verify Application Server and Deployment via execution of soapUI tests. See section 9.2.

4.0 OID REQUEST SUBMITTAL PROCESS

Each gateway has a unique identifier known as the OID (Object Identifier) or Home Community ID. The instructions in Appendix A can be used to request an OID. However, the instructions needed to obtain an OID may be slightly different due to ongoing updates to the site.


5.0 TEST DEPLOYMENT FOOTPRINT

5.1 Hardware Requirements This section describes the recommended minimum hardware component infrastructure including processor performance, disk space, and RAM for the application server platform. This is provisional information subject to change based on continued development.

The Connect software requires two machines, each with the following minimum specifications

:

Item Version 2.0

Processor Minimum dual 2GHz UltraSPARC

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 10000 RPM preferred.

Network Interface 100MB Ethernet acceptable; 1GB Ethernet desirable

5.2 Software Requirements

This section describes any dependent software products.

Item Description Applies to Gateway Version

Platform

Operating System

Operating system supported by Glassfish v2 and GlassFishESB v2.1. For additional information, refer to the specific installation instructions for Solaris.

All Server


Item Description Applies to Gateway Version

Platform

Java-JRE/JDK Java SDK 1.6 Update 13 All Server

Application Server

Glassfish v2.1 (9.1.1) build b60e-fcs [This is bundled with the GlassFishESB]

All Server

Enterprise Service Bus (ESB)

GlassFishESB v2.1 build 20090201 All Server

Communication Stack

Metro v1.4 All Server

Network Protocol

TCP/IP All Server/Client

Relational Database

Any ANSI SQL92 compliant relational database. For example, MySQL 5.0, Oracle, and DB2

1.0 Server

Recommended Dev Environment (Optional)

Netbeans 6.5.1 build 200903161801 All Server/Client

Recommended Test Tools (Optional)

soapUI v2.5.1, JUnit All Client

5.3 Federal Gateway Interface (WSDL) Ports The table below identifies all of the currently public WSDL Interfaces supported by the Federal Gateway. This table includes the name of the WSDL, the services it handles, the port number, whether or not it is configurable, and whether or not it is SSL. All ports in the NHIN-CONNECT Gateway are configurable via either the Glassfish or Http Binding Component port settings.


WSDL Services Port SSL

AdapterAuditLogQuery Audit Log Query HttpDefaultPort No

AdapterDocQuery Document Query HttpDefaultPort No

AdapterDocRetrieve Document Retrieve HttpDefaultPort No

AdapterReidentification

Subject Discovery - Reidentification

HttpDefaultPort No

AdapterSubjectDiscovery

Subject Discovery - Announce and Revoke

HttpDefaultPort No

AdapterSubscriptionManagement

HIEM - Subscribe and Unsubscribe

HttpDefaultPort No

AdapterNotificationConsumer

HIEM - Notify

HttpDefaultPort No

EntityAuditLogQuery Audit Log Query HttpDefaultPort No

EntityDocQuery Document Query HttpDefaultPort No

EntityDocRetrieve Document Retrieve HttpDefaultPort No

EntitySubjectDiscovery Subject Discovery - Announce, Revoke, and Reidentification

HttpDefaultPort No


WSDL Services Port SSL

EntitySubscriptionManagement HIEM - Subscribe and Unsubscribe

HttpDefaultPort No

EntityNotificationConsumer HIEM - Notify

HttpDefaultPort No

NhinAuditLogQuery Audit Log Query 8181

(Glassfish Https Port)

Yes

NhinSubjectDiscovery Subject Discovery - Announce, Revoke, and Reidentification

8181


Yes

NhinDocQuery Document Query 8181


Yes

NhinDocRetrieve Document Retrieve 8181


Yes

NhinSubscription HIEM - Subscribe, Unsubscribe, and Notify

8181


Yes


6.0 SOLARIS INSTALL AND CONFIGURATION INSTRUCTIONS

6.1 Install Prerequisite Software on Solaris The prerequisite software needs to be installed on both the Adapter machine and the Gateway machine.

6.1.1 JDK Installation

Obtain a copy of Java JDK 1.6.0_13 from http://java.sun.com/products/archive/j2se/6u13/index.html.

Specify:

• Platform: Soalris SPARC

• Language: Multi-language

• License Agreement

Select jdk-6u13-solaris-sparc.sh.

Verify execute privilege is set on the shell script. Execute the shell script and follow the instructions. The default location for installation of the JDK is /nhin/jdk. Copy the download to the /nhin/jdk directory to execute the installation.

6.1.2 GlassFishESB Installation Obtain GlassFishESB installer (glassfishesb-full-installer-solaris-sparc-11-09.sh) from the Release package. It is located in the zip file NHIN_CONNECT_2.1_Thirdparty_sol10_0707.tar.gz and can be downloaded from the http://www.connectopensource.org.

1. Run the GlassFishESB installer.


Figure 6.1-1: Glassfish Welcome Screen

2. Click the “Next” button.


Figure 6.1-2: Glassfish License Agreement

3. Accept the license agreement and click “Next”.


Figure 6.1-3: NetBeans Screen

The NetBeans IDE should be installed to /nhin/GlassFishESB/netbeans

The Java Environment should be set to /nhin/jdk/jdk1.6.0_13

4. Click “Next”.


Figure 6.1-4: Glassfish Screen

Glassfish should be installed to /nhin/GlassFishESB/glassfish

The JDK for glassfish should also be /nhin/jdk/jdk1.6.0_13

The default Admin Username is admin, the default Admin Password is adminadmin. You may use the default values, or enter custom values.


It is recommended that the ports be kept at the default values.

5. Click “Next” and then “Install” to begin the installation.

6.2 Configuration

1. Change or create the JAVA_HOME environment variable to point to the newly installed Java path located under the /nhin/GlassFishESB folder.

JAVA_HOME=/nhin/jdk/ jdk1.6.0_13

export JAVA_HOME

2. Change or create the AS_HOME environment variable to point to the Glassfish instance you just created.

AS_HOME=/nhin/GlassFishESB/glassfish export AS_HOME

3. Change or create the ANT_HOME environment variable to point to the Ant directory under Netbeans.

ANT_HOME=/nhin/GlassFishESB/netbeans/java2/ant

export ANT_HOME

4. Update the PATH environment variable to include these installed components.

PATH=${JAVA_HOME}/bin:${PATH}:${ANT_HOME}/bin

export PATH

5. Change or create the NHINC_PROPERTIES_DIR environment variable to point to the NHINC_PROPERTIES_DIR. This value is configurable, but it is suggested that /nhin/GlassFishESB/glassfish/domains/domain1/config/nhin be used.

cd /nhin/GlassFishESB/glassfish/domains/domain1/config

mkdir nhin


NHINC_PROPERTIES_DIR=/nhin/GlassFishESB/glassfish/domains/domain1/config/nhin

export NHINC_PROPERTIES_DIR

NOTE: These environment variables should be stored in the shell resource file for execution on logon.

6. Update the permissions and access to the GlassFishESB directory structure to support runtime access from non-privileged users.

cd /nhin

chmod –R go+rx GlassFishESB

cd /nhin/GlassFishESB/glassfish/domains/domain1

chmod go+w logs

cd /nhin/GlassFishESB/glassfish

chmod –R go+w domains

Verify the permissions on the following directories are 777, if they aren’t issue a “chmod 777 <directory name> on each of those directories:

$AS_HOME/jbi

$AS_HOME/lib

$AS_HOME/addons

$AS_HOME/databases

$AS_HOME/config

$AS_HOME/domains

7. Start the Glassfish application server. Monitor the server.log in $AS_HOME/domains/domain1/logs for status.

cd $AS_HOME/bin

./asadmin start-domain domain1

cd $AS_HOME/domains/domain1/logs


tail –f server.log

After verifying that glassfish will start successfully (log will say “Application server startup complete” then shutdown glassfish with the following command and continue with the installation:

./asadmin stop-domain domain1

There is a documented issue with NetBeans that requires the installation of all references schemas and wsdls to be available at execution time. The installation of these schemas and wsdls is a work-around for the issue to allow resolution of references.

8. Download these interfaces NHIN_CONNECT_2.1_Interfaces_sol10_0707.tar.gz.

cd /nhin

cp $HOME/NHIN_CONNECT_2.1_Interfaces_sol10_0707.tar.gz /nhin/.

gunzip NHIN_CONNECT_2.1_Interfaces_sol10_0707.tar.gz

tar –xvf NHIN_CONNECT_2.1_Interfaces_sol10_0707.tar

This will place all the required schemas and wsdls in /nhin/projects/NHINC/Current/Product/Production/Common/Interfaces/src.

Updated $AS_HOME/domains/domain1/config/domain.xml file with memory management lines updated the following lines to be these memory values:

<jvm-options>-Xmx2048m</jvm-options>

<jvm-options>-XX:MaxPermSize=256m</jvm-options>

<jvm-options>-XX:PermSize=256m</jvm-options>

During initial setup and configuration, additional logging can be enabled by adding the following statements to the domain.xml:

<jvm-options>-Dcom.sun.xml.ws.transport.http.HttpAdapter.dump=true</jvm-options> <jvm-options>-Dcom.sun.xml.ws.transport.http.client.HttpTransportPipe.dump=true</jvm-options> <jvm-options>-Djavax.enterprise.resource.xml.webservices.security.level=FINE</jvm-options> <jvm-options>-Djavax.enterprise.resource.webservices.jaxws=FINE</jvm-options>


6.2.1 Update Property/Configuration File Settings

6.2.1.1 Gateway.properties

This property file contains the main settings for the gateway. Follow the steps outlined below to change this property file.

1. Download the NHIN_CONNECT_2.1_Properties_sol10_0707.tar.gz.

cd $AS_HOME/domains/domain1/config/nhin

cp $HOME/NHIN_CONNECT_2.1_Properties_sol10_0707.tar.gz .

gunzip NHIN_CONNECT_2.1_Properties_sol10_0707.tar.gz

tar xvf NHIN_CONNECT_2.1_Properites_sol10_0707.tar

su

chmod go+w *

exit

2. Edit gateway.properties to set the UDDIInquiryEndpointURL to the external IP.

3. Set the localHomeCommunityId to the OID from Appendix A.

4. Set the locaHomeCommunityDescription to a textual description of your environment.

5. Set the localDeviceId to the local Assigning Authority OID.

6.3 Third Party Components

6.3.1 Component Catalog

This section lists the third party components that are to be added to Glassfish. This catalog is included here for a reference only. These components are included with the release and installation instructions follow.

Log4j:

Vendor/Publisher: Apache

Version: 1.2.15


URL: http://logging.apache.org/log4j/1.2/download.html

Components:

• log4j-1.2.15.jar

Apache Commons Logging:

Vendor/Publisher: Apache

Version: 1.1.1

URL: http://commons.apache.org/downloads/download_logging.cgi

Components:

• commons-logging-1.1.1.jar

Hibernate Relational Persistence for Java:

Vendor/Publisher: Hibernate

Version: 3.2.5 ga

URL:http://sourceforge.net/project/showfiles.php?group_id=40712

Components:

• antlr-2.7.6.jar

• asm-attrs.jar

• asm.jar

• cglib-2.1.3.jar

• commons-collections-2.1.jar

• dom4j-1.6.1.jar

• ehcache-1.2.3.jar

• hibernate3.jar

• jdbc2_0-stdext.jar

• jta.jar

• c3p0-0.9.1.2.jar

Metro:


Vendor/Publisher: Sun Microsystems

Version: 1.4

URL: NHIN Wiki

Components:

• webservices-api.jar

• webservices-rt.jar

• webservices-tools.jar

MySQL Connector / J (Data base drivers to connect to MySQL DB using Java):

Vendor/Publisher: Sun Microsystems

Version: 5.0

URL: http://dev.mysql.com/downloads/connector/j/5.0.html

Components:

• mysql-connector-java-5.0.8-bin.jar

XStream:

Vendor/Publisher: XStream

Version: 1.4

URL: http://xstream.codehaus.org/download.html

Components:

• cglib-license.txt

• cglib-nodep-2.1_3.jar

• commons-lan-license.txt

• dom4j-1.6.1.jar

• dom4j-license.txt

• jdom-1.0.jar

• jdom-license.txt

• jettison-1.0-RC2.jar


• jettison-license.txt

• joda-time-1.5.1.jar

• joda-time-license.txt

• junit-license.txt

• oro-license.txt

• stax-1.2.0.jar

• stax-api-1.0.1.jar

• wootstox-license.txt

• wstx-asl-3.2.3.jar

• xml-writer-0.2.jar

• xom-1.1.jar

• xom-license.txt

• xpp3_min-1.1.4c.jar

• xpp3-license.txt

• xstream-1.3.jar

• xstream-benchmark-1.3.jar

JDK 1.3 Components were included in the XStream download but should NOT be copied:

• xalan-2.7.0.jar

• xalan-license.txt

• xercesImpl-2.8.1.jar

• xerces-license.txt

• xml-apis-1.3.0.4.jar

Spring Framework:

Vendor/Publisher: SpringSource

Version: 2.5.6


URL: http://www.springsource.com/download.html

Components:

• spring.jar

• spring-sources.jar

NHIN CONNECT Gateway Components

• NhincHL7JaxbLib.jar • NhincSAMLCallbackLib.jar

6.3.2 Installation of Third Party Components

This section describes installing required third party components to the existing Glassfish installation. The components described in this section are provided with the release, or may be obtained from their original sources by following the instructions in the next section. The third party components are included in the NHIN_CONNECT_2.1_Thirdparty_sol10_0707.tar.gz. Download the tar and extract the files.

cd $HOME

gunzip NHIN_CONNECT_2.1_Thirdparty_sol10_0707.tar.gz

tar –xvf NHIN_CONNECT_2.1_Thirdparty_sol10_0707.tar

This will place all the third party products in a $HOME/Thirdparty directory.

6.3.2.1 Installation of GNU Tar

The installation of Hibernate on Solaris requires use of GNU tar due to long links that are created due to excessive long filenames. If GNU tar is not already installed on the target server, the following steps need to be executed to complete the MySQL installation.

NOTE: The following steps are executed as a privileged user (root or other).

First determine if GNU tar exists on the target server by

pkginfo –l | grep SMC


Some versions of GNU tar get installed as gtar. To check is gtar is installed on your system enter

gtar --version

If gtar exists, substitute gtar command instead of tar when using GNU tar in the following sections.

If GNU Tar is already installed, SMCtar will be included in the list and you can proceed to section 0.

Now that it has been verified that the dependent libraries have been installed, install the GNU tar.

cd /tmp

cp $HOME/Thirdparty/tar-1.21-sol10-sparc-local.gz /tmp/.

gunzip tar-1.21-sol10-sparc-local.gz

pkgadd –d tar-1.21-sol10-sparc-local

when prompted use “all” option

6.3.2.2 Installation of libiconv libraries

Execute the pkginfo command to verify libiconv is already installed on the target machine. If the libiconv libraries are already installed, SMCliconv will be included in the list.

cd /tmp

cp $HOME/Thirdparty/libiconv-1.11-sol10-sparc-local.gz /tmp/.

gunzip libiconv-1.11-sol10-sparc-local.gz

pkgadd –d libiconv-1.11-sol10-sparc-local


6.3.2.3 Installation of libint libraries

Execute pkginfo command to verify if libintl is already installed on the target machine. If the libraries are already installed, SMClintl will be included in the list.


cd /tmp

cp $HOME/Thirdparty/libintl-3.4.0-sol10-sparc-local.gz /tmp/.

gunzip libintl-3.4.0-sol10-sparc-local.gz

pkgadd –d libintl-3.4.0-sol10-sparc-local


6.3.2.4 Installation of GCC-3.4.6 Libraries

Execute pkginfo command to verify if gcc is already installed. If gcc is already installed, SMCgcc will be included in the list.

cd /tmp

cp $HOME/Thirdparty/libgcc-3.4.6-sol10-sparc-local.gz /tmp/.

gunzip libgcc-3.4.6-sol10-sparc-local.gz

pkgadd -d libgcc-3.4.6-sol10-sparc-local


6.3.2.5 Installation of Log4j

NOTE: For this installation do not use the tar command, and ensure you download the .zip file. At the time of writing these instructions, the tar.gz file found on the apache download site, has issues with Solaris tar and GNU tar. The following steps are executed as a privileged user.

cd /nhin

cp $HOME/Thirdparty/apache-log4j-1.2.15.zip /nhin

unzip apache-log4j-1.2.15

6.3.2.6 Installation of Commons Logging

NOTE: For this installation do not use the tar command, and ensure you download the .zip file. At the time of writing these instructions, the tar.gz file found on the apache download site, has issues with Solaris tar and GNU tar. The following steps are executed as a privileged user.

cd /nhin


cp $HOME/Thirdparty/commons-logging-1.1.1-bin.zip

unzip commons-logging-1.1.1-bin

6.3.2.7 Installation of c3p0

The following steps are executed as a privileged user.

cd /nhin

cp $HOME/Thirdparty/c3p0-0.9.1.2.bin.zip /nhin/.

unzip c3p0-0.9.1.2.bin.zip

6.3.2.8 Installation of Hibernate

This is using the GNU tar installed into /usr/local. The following steps are executed as a privileged user.

cd /nhin

cp $HOME/Thirdparty/hibernate-3.2.5.ga.tar.gz /nhin

/usr/local/bin/tar xzvf hibernate-3.2.5.ga.tar.gz

6.3.2.9 Installation of copyv3

The installation of copyv3 is only required when running with the default security certificates provided with Glassfish. If you are using certificates and Assigning Authority, this step can be omitted. The following steps are executed as a privileged user.

1. The installation of copyv3 requires Apache Ant. This is using the copy of GNU tar installed previously.

cd /nhin

cp $HOME/Thirdparty/apache-ant-1.7.1-bin.tar.gz

/usr/local/bin/tar xzvf apache-ant-1.7.1-bin.tar.gz

2. Now install copyv3.

cd /nhin


cp $HOME/Thirdparty/copyv3.zip /nhin/.

unzip copyv3.zip

cd copyv3

JAVA_HOME=/nhin/jdk/jdk1.6.0_13

export JAVA_HOME

AS_HOME=/nhin/GlassFishESB/glassfish

export AS_HOME

/nhin/apache-ant-1.7.1/bin/ant

After the installation is completed you should be returned to the command prompt. We have experienced the cert installation hang while attempting to start the Appserver; and this requires an interrupt.

3. To verify the installation was successful check the certificate fingerprints.

cd $AS_HOME/domains/domain1/config

/nhin/jdk/jdk1.6.0_13/bin/keytool -list -keystore cacerts.jks -alias wssip -storepass changeit

nhin/jdk/jdk1.6.0_13/bin/keytool -list –keystore keystore.jks -alias xws-security-server -storepass changeit

Note: If the certificates were installed correctly, you will see something similar to the following responses.

Certificate fingerprint (MD5): 1A:0E:E9:69:7D:D0:80:AD:5C:85:47:91:EB:0D:11:B1

Certificate fingerprint (MD5): 1A:0E:E9:69:7D:D0:80:AD:5C:85:47:91:EB:0D:11:B1

If the certificates were not installed correctly, you will see something similar to the following responses.

keytool error: java.lang.Exception: Alias <wssip> does not exist

keytool error: java.lang.Exception: Alias <xws-security-server> does not exist

4. To grant access to the CONNECT certificates enter:


chmod go+rw *.jks

6.3.2.10 Installation of Metro


Now install Metro.

cd /nhin

cp $HOME/Thirdparty/metro-1_4-installer-nightly_02_05_09.jar /nhin/.

/nhin/jdk/jdk1.6.0_13/bin/java –jar metro-1_4-installer-nightly_02_05_09.jar –console

At the prompt asking whether to accept the license enter A.

cd metro

/nhin/apache-ant-1.7.1/bin/ant –f metro-on-glassfish.xml install

6.3.2.11 Installation of Connector/J for MySQL

The following steps are executed as a privileged user. The GNU tar is used due to long filenames.

cd /nhin

cp $HOME/Thirdparty/mysql-connector-java-5.0.8.tar.gz /nhin/.

/usr/local/bin/tar xzvf mysql-connector-java-5.0.8.tar.gz

6.3.2.12 Installation of XStream


cd /nhin

cp $HOME/Thirdparty/xstream-distribution-1.3.1-bin.zip /nhin/.

unzip xstream-distribution-1.3-bin.zip

6.3.2.13 Installation of Spring Framework



cd /nhin

cp $HOME/Thirdparty/spring-framework-2.5.6.SEC01-with-docs.zip /nhin/.

unzip spring.framework-2.5.6.SEC01-with-docs.zip

6.3.2.14 Installation of soapUI


cd /nhin

cp $HOME/Thirdparty/soapui-2.5.1-bin.zip

unzip soapui-2.5.1-bin.zip

cd /nhin/soapui-2.5.1/bin

chmod +x soapui.sh

cd /nhin

chmod –R go+w soapui-2.5.1

6.3.3 Configure Third Party Components in Glassfish

The successful execution of the NHIN CONNECT Gateway requires some of the third party products to be placed in the GlassFishESB/glassfish/lib directory. A script is provided in the release to perform the copy. The Glassfish application server must be stopped during the copy. The application server will then resolve the required references on restart.

cd $AS_HOME/bin

$HOME/Thirdparty/NHIN_CONNECT_Copy3rdPartyToGFLib.sh


Monitor the $AS_HOME/domains/domain1/logs/server.log for the Application server startup complete or JBI framework startup complete message prior to proceeding.

The message you get will depend on whether the http binding component is running or not.


6.4 Install and Configure MySQL

The Gateway and the reference implementation of the Adapter both use MySQL when a database is necessary. The programmatic access to this database was done using Hibernate. When doing the initial installation of the Gateway and Adapter, it is recommended that MySQL be installed and that the system be verified. After it has been created and verified, other relational databases can be used in place of MySQL by altering the appropriate entries in the hibernate configuration files for those projects which are accessing the database. Directions for configuring hibernate to use other databases is not defined in this document. Set up the database using the following sequence of steps.

6.4.1 Installation

Change the current user to root and add a user and group for mysqld.

su

groupadd mysql

useradd –g mysql mysql

cd /nhin

/usr/local/bin/tar xvf $HOME/Thirdparty/mysql-5.0.77-solaris10-sparc-64bit.tar

The tar command will create the directory “mysql-5.0.77-solaris10-sparc-64bit”.

This directory is owned by root and needs to be owned by mysql. This can be done by executing the following commands as root in the installation directory. Create MySQL data directory and Change the owner ship to mysql user from root

cd mysql-5.0.77-solaris10-sparc-64bit

chown –R mysql *

chgrp –R mysql *

scripts/mysql_install_db –u mysql

6.4.2 Starting and Stopping MySQL

To start MySQL make sure you are in MySQL installed directory “/nhin/ mysql-5.0.77-solaris10-sparc-64bit”

bin/mysqld_safe –u mysql &


NOTE: If you run the command as root, you must use the –user option as shown. The value of the option is the name of the login account that you created in the step to use for running the server.

Since we have not setup and password for “root” user we are fine to use the above said command. To set up the password for MySQL root user uses the command below:

bin/mysqladmin –u root password NHIE-Gateway

To verify the installation after starting the Server execute few of the following commands:

bin/mysqladmin –pNHIE-Gateway version

This command will show the complete version history of the MySQL installation and its Solaris Socket file path etc.,

To stop MySQL Server, make sure you are still using MySQL installed directory path: “/nhin/ mysql-5.0.77-solaris10-sparc-64bit” and execute the command below to Stop the MySQL Server.

NOTE: This command is being specified for INFORMATIONAL purposes only. Do NOT execute it at this time.

bin/mysqladmin -uroot –pNHIE-Gateway shutdown

6.4.3 Configuring MySQL

To configure the database schemas and tables associated with the NHIN-CONNECT Gateway, a script is provided named “nhincdb.sql” file under Thirdparty folder.

From the MySQL directory, create a database connection and create the schemas

cd /nhin/mysql-5.0.77-solaris10-sparc-64bit

bin/mysql –uroot –pNHIE-Gateway

mysql>CREATE DATABASE nhincdb;

mysql>\q

bin/mysql -uroot -pNHIE-Gateway nhincdb < $HOME/Thirdparty/dropall.sql

bin/mysql -uroot -pNHIE-Gateway nhincdb < $HOME/Thirdparty/nhincdb.sql

This will create Gateway Schemas as listed below: i) aggregator


ii) assigningauthoritydb iii) auditrepo iv) docrepository v) patientcorrelationdb vi) subscriptionrepository

Try and log into the database as the nhincuser to verify it got created successfully bin/mysql –unhincuser –pnhincpass If this command fails then issues the following commands: bin/mysql –uroot –pNHIE-Gateway mysql> CREATE USER ‘nhincuser’@’localhost’ IDENTIFIED BY ‘nhincpass’; mysql> GRANT ALL PRIVILEGES ON *.* TO ‘nhincuser’@’localhost’ WITH GRANT OPTION; mysql> quit Try to log in as nhincuser again: bin/mysql –unhincuser –pnhincpass

7.0 SSL CERTIFICATE REQUEST AND INSTALLATION PROCESS

This section outlines how to add 2-way SSL to an existing working system, such as the NHIN CONNECT Gateway.

To use 2-way SSL, there are two components needed. First, the server must present a certificate identifying itself to the consumer of its services. This server certificate must match (the server portion of the URL or the service must be the same as the name on the certificate) and must be trusted (accomplished by having the issuer of the certificate as a trusted root certificate authority on the client). Second, the client must send a certificate to the server to identify itself. This client certificate must be trusted by the server (by having the trusted root certificate on the server) (there does not appear to be any validation of the client cert to ensure that it came from a certain address).

Glassfish comes with a default keystore to use for presenting the server certificate. Instead of using the default keystore, a new keystore will be created, which will hold a certificate issued by the trusted root authority - NHIN-CN. Glassfish also comes with a default trust store used to validate remote certificates - in this case, to determine if it trusts the client cert.

NOTE: This section only applies to the NHIN CONNECT Gateway machine. This section is not applicable to the NHIN CONNECT Adapter machine.


7.1 Setup

1. Note: ensure that ports are opened on the firewall to allow traffic to the server. The NHINC gateway uses ports 8080 and 9080 for HTTP traffic (this is used for the entity interface) and ports 8181 and 9081 for HTTPS traffic (this is used for the NHIE interfaces).

7.2 Generate Certificate Request

2. Create a new working "certificate request" directory (i.e., /nhin/GlassFishESB/certificaterequests).

3. Open a command prompt to the "certificate request" directory. 4. Create the new keystore by running the following command:

/nhin/jdk/jdk1.6.0_13/bin/keytool - genkeypair -keyalg RSA -keysize 2048 -keystore gateway.jks -keypass xxxxxxxx -storepass xxxxxxxx -validity 365 -alias gateway -dname "[email protected], cn=testgateway.fedsconnect.org, OU=Testing, O=YourOrganization, L=YourCity, S=YourState, C=US"

Note on parameters:

-keystore: This is the name of the java keystore that will be created. This can be modified if desired. -keypass -storepass: This sets the passwords for the store and the request. Replace xxxxxxxx with your password. The keystore and store passwords should be the same. -dname:

o EmailAddress: Email address for the point of contact for your network.

o CN: This domain must match the domain of the address of the services. Replace testgateway.fedsconnect.org with the name of your gateway.

o OU: Organizational Unit aspect of the name.

o O: Replace YourOrganization with the name of your organization.

o L: Replace YourCity with the city your server is hosted in.

o S: Replace YourState with the state your server is hosted in.

5. Create a request for the certificate by running the following command (the request must be made from the server that will use the request):


/nhin/jdk/jdk1.6.0_13/bin/keytool -certreq -alias gateway -sigalg SHA1withRSA -keystore gateway.jks -storepass xxxxxxxx -file testgateway.fedsconnect.org.csr

Note on the parameters: -alias: This sets a name that will refer to this cert. This can be change if desired. -keystore: This must be the same name as the keystore created above. -storepass: This must be the same as the password specified when creating the keystore -file: This is the filename of the certificate request. This can be changed if desired. NOTE: Use of the –file option has caused some certificate requests to have imbedded CR/LF. If the certificate authority reports this anomaly in your request, remove the –file option and grab the output and paste into a file manually.

7.3 Download Root Certificate

6. Download the Root Certificate, onc_ca.arm from the NHIN Certificate Authority at http://ca.nhinteam.com/certificate?id=1

o The browser will display a page with text. Copy all of the text until the line that contains this text: -----END CERTIFICATE-----

o Open a new text document in your Certificate Request directory. Copy the paste into this text document. Ensure there are no extra spaces after the text: -----END CERTIFICATE-----

o Save the file as onc_ca.arm.

7.4 Send Certificate request

• Upload the generated certificate request (*.csr) to the certificate authority (currently, http://ca.nhinteam.com/submit.jsp ). It normally takes one working day for the request to be signed. The signed certificate can be downloaded here: http://ca.nhinteam.com/listcerts.jsp

7.5 Install the certificate

Update the keystore with the response. This will update the server certificate in the keystore to have an issuer of nhin-cn. Save these files to your working "certificate request" directory.

• Import the certificate authority certificate into the keystore. This is the certificate that was downloaded in step 6.3 above.

/nhin/jdk/jdk1.6.0_13/bin/keytool -import -v -trustcacerts -alias onc_ca -file onc_ca.arm -keystore gateway.jks


When prompted, enter the password for your keystore. Note on the parameters: -alias: This is how the alias for the certificate authority. This can be modified if desired. -file: This points to the certificate authority file (*.arm) file. It is not expected that this will vary. -keystore: This must point to the keystore used in the request.

When prompted with “Trust this certificate? [no]:” enter yes.

• Import the server certificate into the keystore.

/nhin/jdk/jdk1.6.0_13/bin/keytool -import -v -alias gateway -file fedcrsp.arm -keystore gateway.jks

When prompted, enter the password for your keystore. Note on the parameters: -alias: This must match the alias given during the creation of the request -file: This points to the certificate request response file (*.arm) file. This is the file received from the certificate authority. -keystore: This must point to the keystore used in the request.

• Locate the trusted root authority store. By default, this store will be located in: <glassfish>/domains/<domain directory>/config/cacerts.jks. It is advisable to backup the cacerts.jks file at this time.

• Import the trusted root certificate into the trusted root authority store.

/nhin/jdk/jdk1.6.0_13/bin/keytool -import -v -trustcacerts -alias onc_ca -file onc_ca.arm -keystore <path>/cacerts.jks

When prompted with “Trust this certification? [no]” enter yes.

Note on the parameters: -alias: This is how the alias for the certificate authority. This can be modified if desired. -file: This points to the certificate authority file (*.arm) file. It is not expected that this will vary. -keystore: This must point to the certificate authority store. You will be prompted for a password. The default glassfish password is “changeit”. If you have changed this value, use the updated value instead.


• Validate the certificates were imported correctly by viewing the store. You will be prompted for the passwords after each execution of the keytool utility.

/nhin/jdk/jdk1.6.0_13/bin/keytool -list -v -alias gateway -keystore gateway.jks /nhin/jdk/jdk1.6.0_13/bin/keytool -list -v -alias onc_ca -keystore gateway.jks /nhin/jdk/jdk1.6.0_13/bin/keytool -list -v -alias onc_ca -keystore <path>/cacerts.jks

This should output each of the certificates. If the certificate was not imported, there will be an error from the keytool.

• Copy the keystore (gateway.jks) to the domain's config directory (<glassfish>/domains/<domain directory>/config/).

• Open the domain configuration file for editing. (<glassfish>/domains/<domain directory>/config/domain.xml). (Alternately, these changes can be made by using the admin console)

• Update the domain configuration to point to the new keystore and supply the password (the password option is not in the original configuration). To do this, replace: <jvm-options>-Djavax.net.ssl.keyStore=${com.sun.aas.instanceRoot}/config/keystore.jks</jvm-options> to <jvm-options>-Djavax.net.ssl.keyStore=${com.sun.aas.instanceRoot}/config/gateway.jks</jvm-options> <jvm-options>-Djavax.net.ssl.keyStorePassword=xxxxxxxx</jvm-options>

• Replace xxxxxxxx with the password you created above. • Update the domain configuration to use the new server certificate. To do this, replace

all instances of "s1as" with the updated certificate alias ("gateway"). In our default server, there were 12 instances of the certificate alias to update.

• Enable two-way SSL. This is done by adding the following: <jvm-options>-Dcom.sun.jbi.httpbc.enableClientAuth=true</jvm-options>

8.0 NHIN-CONNECT SERVER CONFIGURATION

Configuration settings for the Gateway are predominately platform independent. Any platform specific items are explicitly stated. The settings listed below need to be applied to both the Adapter machine and the Gateway machine.

8.1 Configuration Settings

8.1.1 Metro 1.4 Installation Settings

Update $AS_HOME/domains/domain1/config/domain.xml file. Add the following lines to deal with the certificate and other items in domain.xml toward the end of the file within the existing block of <jvm-options> tags:

 <jvm-options>-Dcom.sun.jbi.httpbc.enableClientAuth=true</jvm-options> <jvm-options>-Djavax.net.ssl.keyStore=${com.sun.aas.instanceRoot}/config/gateway.jks</jvm-options>

<jvm-options>-Djavax.net.ssl.keyStorePassword=XXXXX</jvm-options> <jvm-options>-Djavax.net.ssl.trustStore=${com.sun.aas.instanceRoot}/config/cacerts.jks</jvm-options> <jvm-options>-Djavax.net.ssl.trustStorePassword=changeit</jvm-options> <jvm-options>-DSERVER_KEY_ALIAS=gateway</jvm-options> <jvm-options>-DCLIENT_KEY_ALIAS=gateway</jvm-options>

NOTE: The KeyStore password will be the same keystore password generated in the certificate request.

8.1.2 Glassfish Application Variables

NhincHttpPort is used to identify the default Glassfish Http port so Composite Applications can communicate with EJBs. This value is customizable. The recommended setting is 8080. It must match the default http port selected when installing glassfish.

The value can be set through the Glassfish Admin Console. To set, you will need to first log on to the glassfish admin console. Open the URL http://localhost:4848/login.jsf. The default user name is admin and the default password is admin/adminadmin. If you customized any of these settings in your installation, use your custom settings instead.

During some installations of Glassfish, the sun-http-binding component initializes in the stopped state. The sun-http-binding component needs to be running to assign the Application Variable.

1. From the main page, select JBI Components sun-http-binding

2. Verify that the sun-http-binding component is started. If not, select the Start button on the sun-http-binding – Binding Component General Properties page.

3. From the sun-http-binding page, select Application Variables

4. Click the “Add Variable” button. Variable type is Number, and the desired value (8080 is recommended). The variable name is NhincHttpPort.


Figure 8.1-1: Manage Application Variables

8.2 Connection Management

This section is provided for documentation purposes only. This section will guide the user through any configuration changes needed.

The NHIN Service Registry is responsible for managing connections in the NHIN CONNECT gateway. There are two places that connection information is configured. First, the NHIN UDDI registry is managed by the NHIN and contains connection information for the other NHIN members. A service runs under glassfish called the UDDI Update Manager which periodically queries the NHIN UDDI Service Registry and retrieves the current connection information. This information is placed in the uddiConnectionInfo.xml file which is located in the $NHINC_PROPERTIES_DIR. This file should not be changed by hand. Any changes made by hand to this file will be overwritten the next time the UDDI Update Manager queries the NHIN UDDI service registry.

In addition, an internal connection XML file may also be configured to override the settings obtained from the NHIN UDDI server. It is also used to contain connection information that is internal to the NHIN CONNECT software (e.g. Not published to the NHIN) . This file is called


internalConnectionInfo.xml and is also located in the $NHINC_PROPERTIES_DIR. Endpoint URL connection information in this file will take precedence over the connection information in the uddiConnectionInfo.xml file. If there is a setting in both places for the same service and home community ID, then the one in the internalConnectionInfo.xml file will be used.

One additional configuration file is needed during connection management. It is called, connectionEPR.properties. This file contains information about each service that is necessary when dynamically changing the endpoint URL for a service. This file should not be changed. It is the same for every NHIN CONNECT site. Changing any of the settings in this file could cause the NHIN CONNECT software to fail.

The NHIN CONNECT connection management services monitor the last-modified timestamp on both the uddiConnectionInfo.xml and the internalConnectionInfo.xml file. If a change is made to either file, the new connection information is automatically used. You do not need to restart glassfish after making a change to the internalConnectionInfo.xml file or when the UDDI Update Manager updates the uddiConnectionInfo.xml file.

There are a handful of properties in the gateway.properties file that are used to configure the NHIN CONNECT for communicating with the NHIN UDDI Service Registry. The following are settings you will see:

• UDDIInquiryEndpointURL: This is the endpoint URL for the UDDI Service Registry Inquiry service. Currently this should be set to: http://12.54.145.57:8080/uddi/services/inquiry if your gateway is outside of the DMZ and if it is within the DMZ, then it should be set to: http://172.16.50.57:8080/uddi/services/inquiry

• UDDIBusinessesToIgnore: This contains a list of services, separated by semicolons that are defined in the UDDI Service Registry which should be ignored and not considered as real connections. Currently this should be set to the following string: uddi:replication:findbusiness;uddi:replication:findtmodels;uddi:nhinregistry:node

• UDDIRefreshDuration: This is the number of seconds between the time the UDDI Update Manager queries the NHIN UDDI Service Registry and re-creates the uddiConnectionInfo.xml file.

• UDDIRefreshKeepBackups: If set to true, then when the uddiConnectionInfo.xml file is updated, a backup is made by renaming the current file and appending the date and time. If set to false, then no back up is maintained.

• InternalConnectionRefreshDuration: This property is currently not in use.

• InternalConnectionRefreshKeepBackups: This property is currently not in use.

8.2.1 InternalConnectionInfo.xml File

The internalConnectionInfo.xml file can be used to override settings obtained by the NHIN UDDI Service Registry as well as to configure endpoints that are internal to NHIN CONNECT

and not published to the NHIN. This section describes the format of this file. The following is a sample of the internal connectionInfo.xml file.

<InternalConnectionInfos>  <internalConnectionInfo> <homeCommunityId>2.16.840.1.113883.3.200</homeCommunityId> <name>VA</name> <description>VA</description> <services>  <service> <name>subjectdiscovery</name> <description>NHIN CONNECT Subject Discovery Service</description> <endpointURL>https://dvanhie1.fedsconnect.org:8181/PIXConsumer_Service/SubjectDiscovery</endpointURL> </service> </services> </internalConnectionInfo> <internalConnectionInfo> <homeCommunityId>2.16.840.1.113883.3.198</homeCommunityId> <name>DoD</name> <description>DoD</description> <services> <service> <name>subjectdiscovery</name> <description>NHIN-CONNECT Subject Discovery Service</description> <endpointURL>https://mhsnhie1.fedsconnect.org:8181/PIXConsumer_Service/SubjectDiscovery</endpointURL> </service> <service> <name>notificationconsumer</name> <description>NHIN CONNECT HIEM Notify Service</description> <endpointURL> https://localhost:8181/NotificationConsumerService/HiemNotify </endpointURL> </service> </services> </internalConnectionInfo> </InternalConnectionInfos>

When connection manager determines a connection endpoint, it uses the value in the <service>/<name> tag along with the value in the <homeCommunityId> tag. Note that if you are overriding a service from the uddiConnectionInfo.xml file, the <service>/<name> should be identical to the <uniformServiceName> in the uddiConnectionInfo.xml file. Also note that the <internalConnectionInfo>/<name> and <internalConnectionInfo>/<description> does NOT override settings for these fields in the uddiConnectionInfo.xml file. The only overrides that occur are the service level connection information.


The internalConnectionInfo.xml file is located in the $NHINC_PROPERTIES_DIR defined earlier in this section.

8.3 Reidentification.xml

This file is used on the adapter to keep the mappings between a patient pseudonym and its corresponding real patient identifier.

The reidentification.xml file is located in the $NHINC_PROPERTIES_DIR defined earlier in this section.

8.4 Gateway Properties

The gateway properties are defined in the following file:

$NHINC_PROPERTIES_DIR/gateway.properties

The settings include:

• CacheRefreshDuration: This is used to determine how often the property information is cached. Setting it to 0, means that it is not cached and is re-read every time the property is accessed. Setting it to -1, or omitting this property means that it is cached indefinitely (until Glassfish is restarted), and setting it to a value > 0 is the number of seconds that the cache is kept in memory.

• localHomeCommunityId: The local home community OID for a particular instance of the NHIN CONNECT Gateway.

• localHomeCommunityDescription: The local home community description for a particular instance of the NHIN CONNECT Gateway.

• localDeviceId: The local home community’s assigning authority OID for a particular instance of the NHIN CONNECT Gateway.

• serviceDocumentQuery: This flag indicates if this instance of the NHIN CONNECT

Gateway should service document query requests.

• documentQueryPassthrough: This flag indicates if this instance of the NHIN CONNECT Gateway should pass document query requests directly to the Adapter Interface.

• documentQueryQuerySelf: This flag is used to indicate if a document query should be

performed on our own gateway. If the flag is set to false, only remote gateways are queried. If set to true, our own gateway is queried along with the remote gateways.


• serviceDocumentRetrieve: This flag indicates if the instance of the NHIN CONNECT Gateway should service document retrieve requests.

• documentRetrievePassthrough: This flag indicates if this instance of the NHIN

CONNECT Gateway should pass document retrieve requests directly to the Adapter Interface.

• serviceSubjectDiscovery: This flag indicates if the instance of the NHIN CONNECT

Gateway should service subject discovery requests.

• subjectDiscoveryPassthrough: This flag indicates if this instance of the NHIN CONNECT Gateway should pass subject discovery requests directly to the Adapter Interface.

• serviceAuditRepository: This flag indicates if the instance of the NHIN CONNECT

Gateway should service audit log/query requests.

• auditRepositoryPassthrough: This flag indicates if this instance of the NHIN CONNECT Gateway should pass audit query requests directly to the Adapter Interface.

• serviceSubscription: This flag indicates if the instance of the NHIN CONNECT

Gateway should service HIEM subscribe and unsubscribe requests.

• subscriptionPassthrough: This flag indicates if this instance of the NHIN CONNECT Gateway should pass HIEM subscribe and unsubscribe requests directly to the Adapter Interface.

• serviceNotify: This flag indicates if the instance of the NHIN CONNECT Gateway

should service HIEM notify requests.

• notifyPassthrough: This flag indicates if this instance of the NHIN CONNECT Gateway should pass HIEM notify requests directly to the Adapter Interface.

• aggregatorGarbageCollectionTimeDuration: This is the duration in seconds of the time between garbage collection threads that are run on the aggregation database. Garbage collection cleans up stale aggregator transactions so that the database is self-maintaining.

• aggregatorGarbageCollectionStaleDuration: This is the amount of time in seconds that must pass before an aggregator transaction is considered stale and available for garbage collection.


• NotificationConsumerEndpointAddress: The value stored with this property is included in a subscription message when the local gateway creates a document subscription message that is sent to a remote gateway. This value is included to indicate where the remote gateway should send documents that correspond to the document subscription. “https://mhsnhie1.fedsconnect.org:8181/ NotificationConsumerService/HiemNotify” is a sample value.

• subscription.repository.implementation.class: This property defines the type of subscription repository used. Initially, only a file based repository is supported and the value of “gov.hhs.fha.nhinc.subscription.repository.service.FileSubscriptionRepository” is required. This property will allow changing the type of repository to a different type like a database if that is supported at a future date.

• subscription.repository.file.name: This property is used if the “subscription.repository.implementation.class” is a file based subscription repository. The file name used by the subscription repository if document subscriptions are stored in the file system. If the value of “subscriptionList.xml” is entered for this property, the subscription repository as a file will be stored in the “config” directory of the Glassfish domain. On a Windows operating system, the given entry would result in the file “C:\GlassfishESB\glassfish\domains\domain1\config\ subscriptionList.xml” being created and used as the subscription repository.

• UDDIInquiryEndpointURL: This is the endpoint URL for the UDDI Service Registry Inquiry service. Currently this should be set to: http://12.54.145.57:8080/uddi/services/inquiry if your gateway is outside of the DMZ and if it is within the DMZ, then it should be set to: http://172.16.50.57:8080/uddi/services/inquiry

• UDDIBusinessesToIgnore: This contains a list of services, separated by semicolons that are defined in the UDDI Service Registry which should be ignored and not considered as real connections. Currently this should be set to the following string: uddi:replication:findbusiness;uddi:replication:findtmodels;uddi:nhinregistry:node

• UDDIRefreshDuration: This is the number of seconds between the time the UDDI Update Manager queries the NHIN UDDI Service Registry and re-creates the uddiConnectionInfo.xml file.

• UDDIRefreshKeepBackups: If set to true, then when the uddiConnectionInfo.xml file is updated, a backup is made by renaming the current file and appending the date and time. If set to false, then no back up is maintained.

• InternalConnectionRefreshDuration: This property is currently not in use.

• InternalConnectionRefreshKeepBackups: This property is currently not in use.

• PdpEntityName: Determines which PDP the Policy Engine will use. Options are: ‘ConnectOpenSSO’ or ‘Jericho’. The default value is ConnectOpenSSO.


8.5 Adapter Properties

The adapter.properties file is used to hold reference adapter specific properties. This file should be located in: $NHINC_PROPERTIES_DIR.

• XDSbHomeCommunityId: This setting specifies the home community ID for the document registry/repository associated with this adapter

• EntityNotificationConsumerURL: This is the URL for the Gateway’s Entity HIEM Notify service.

• assigningAuthorityId: This is the local assigning authority id.

8.6 Connection EPR Properties

The connectionEPR.properties is used with the new Connection Manager. Please note that you should not change the contents of this file. This file is maintained in coordination with the NHIN CONNECT software. A description of the contents is placed here for information purposes. The new connection manager is the one that implements the NHINC Service Registry that will enable connection information to be maintained by a UDDI server. During the implementation of this, additional methods were added to simplify the ability to get endpoints that can be used by Glassfish to do dynamic endpoints. This property file contains properties that were previously hard coded when doing dynamic endpoints. For each WSDL that is used with dynamic endpoints, the following set of properties need to be defined. The properties will be defined with the following format: <UniformServiceName>.<Property>=<value>. Where <UniformServiceName> is the name defined in the UDDI server for that service, <Property> is the name of the property, and <Value> is the value to be used for that property. The following is a list of all of the <Property> settings that should be in the file.

• NameSpaceURI: The URI for the namespace for the WSDL.

• PortName: The port name defined for this WSDL.

• ServiceName: The service name defined for this WSDL.

• NamespacePrefix: The name space prefix defined for this WSDL.

The connectionEPR properties are defined in the following file:

$NHINC_PROPERTIES_DIR/connectionEPR.properties

8.7 Component Proxy Spring Configuration properties

There is a collection of configuration files that are used by Spring to determine how the messaging proxy projects communicate. These files are located in $NHINC_PROPERTIES_DIR and follow the following naming convention: <Component Name>ProxyConfig.xml. Below is an example of one of these files. In order to switch out implementations just replace with class name specified with the desired implementation class.

<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd">



<bean id="mpi" class="gov.hhs.fha.nhinc.mpi.proxy.AdapterMpiWebServiceProxy"/>

</beans>

8.8 HIEM Topic Configuration Properties

This properties file contains information needed to process HIEM topics. This file needs to be located in $NHINC_PROPERTIES_DIR and is called hiemTopicConfiguration.xml. Below is an example of the contents within this file.

<topicConfigurations> <topicConfiguration> <topic><![CDATA[ <wsnt:Topic xmlns:wsnt="http://docs.oasis-open.org/wsn/b-2" xmlns:nhin="http://www.hhs.gov/healthit/nhin" Dialect="http://doc.oasis-open.org/wsn/t-1/TopicExpression/Simple" >nhin:SomeOtherTopic1</wsnt:Topic> ]]></topic> <isSupported>true</isSupported> <isPatientCentric>false</isPatientCentric> <isPatientRequired>false</isPatientRequired> <patientIdentifierSubscribeLocation>test subscribe location</patientIdentifierSubscribeLocation> <patientIdentifierNotifyLocation>test notify location 1</patientIdentifierNotifyLocation> <patientIdentifierFormat>HL7Encoded</patientIdentifierFormat>

</topicConfiguration>

</topicConfigurations>

9.0 DEPLOYMENT

The Adapter and Gateway components are included in NHIN_CONNECT_2.1_Gateway_sol10_0707.tar.gz. Download this file and extract the contents. This will create a NHINC_Binaries directory which contains all the components.

cd $HOME

gunzip NHIN_CONNECT_2.1_Gateway_sol10_0707.tar.gz

tar –xvf NHIN_CONNECT_2.1_Gateway_sol10_0707.tar


9.1 Deploying applications to Glassfish

This section describes how deploy the NHIN-CONNECT applications to the Glassfish servers.

9.1.1 Adapter Components.

The following applications must be deployed as part of the Adapter:

Filename Application Type

AdapterReidentficationEJB.jar EJB

AdapterPoliceyEngineTransformEJB.jar EJB

AdapterPIPEJB.jar EJB

AdapterPEPEJB.jar EJB

AdapterPolicyEngineOrchestratorEJB.jar EJB

AdapterMpiEJB.jar EJB

MpiManagerEJB.jar EJB

MpiEJB.jar EJB

AdapterCA.zip CA

DocumentRepositoryEJB.jar EJB

Each of the applications above will be deployed via the Glassfish admin console.

9.1.2 Gateway Components

The following applications must be deployed as part of the Gateway:


AggregatorEJB.jar EJB



AuditRepositoryEJB.jar EJB

AuditLogEJB.jar EJB

ConnectionManagerEJB.jar EJB

DocumentTransformEJB.jar EJB

EntityAuditLogQueryEJB.jar EJB

EntityHiemSubscriptionEJB.jar EJB

GatewaySubscriptionRepositoryEJB.jar EJB

GatewayPolicyEngineFacadeEJB.jar EJB

GatewayPolicyEngineTransformationEjb.jar EJB

NhincAuditLogDteEJB.jar EJB

NhincAuditQueryEJB.jar EJB

NhincDocQueryEJB.jar EJB

NhincDocRetrieveEJB.jar EJB

NhincHiemSubscriptionEJB.jar EJB

NhincSubDiscDataTransformEJB.jar EJB

NhincSubjectDiscoveryEJB.jar EJB



PatientCorrelationEJB.jar EJB

PatientCorrelationFacadeDTEEjb.jar EJB

PropAccessorEJB.jar EJB

SubscriptionDteEjb.jar EJB

UDDIUpdateManagerEJB.jar

Note: this does not get automatically deployed in the script, must deploy manually if desired.

EJB

EntityCA.zip CA

NhinCA.zip CA

9.1.3 Update Glassfish lib

cp $HOME/NHINC_Binaries/NhincSAMLCallbackLib.jar $AS_HOME/lib

cp $HOME/NHINC_Binaries/NhincHL7JaxbLib.jar $AS_HOME/lib

Verify that these jars are owned by your current user. If not, perform the following steps:

su

chown <currentuser> $AS_HOME/lib/NhincSAMLCallbackLib.jar

chgrp <currentuser> $AS_HOME/lib/NhincSAMLCallbackLib.jar

chown <currentuser> $AS_HOME/lib/NhincHL7JaxbLib.jar

chgrp <currentuser> $AS_HOME/lib/NhincHL7JaxbLib.jar

Restart the Glassfish application server.


cd $AS_HOME/bin

./asadmin stop-domain domain1


9.1.4 Deployment of CONNECT

Deployment on Solaris deploys both the Adapter and Gateway on a single machine. Scripts are provided in the NHIN_CONNECT_2.1_Gateway_sol10_0707.tar.gz.

The following sections describe how to deploy for the different configurations. During the deployment, there will be several expecting WARNING messages in the server.log. These are a few of the expected warnings.

<timestamp>|WARNING|sun-appserver2.1|…datatypes-base.xsd…warning: p-props-correct-2.2: maxOccurs must be greater than or equal to 1.|#]

<timestamp>|WARNING|sun-appserver2.1|…FromXmlParser.endElement(): Found unrecognized end element </sxed:editor>, namespace=http://…SUNExtension/Editor|#]

9.1.4.1 Deployment of the Adapter and Gateway to Single Machine

Deployment of the Adapter and Gateway components on a single machine required the Glassfish Application Server to be running. Monitoring the server.log file is required to verify successful deployment.

$AS_HOME/bin/asadmin start-domain domain1

Monitor $AS_HOME/domains/domain1/logs/server.log for JBI framework startup complete message.

$HOME/NHINC_Binaries/DeployAllBinaries.sh

Monitor $AS_HOME/domains/domain1/logs/server.log for any exceptions.

9.2 Configuration Files This section describes the configuration files that are needed by Glassfish in order to run the NHIN CONNECT Gateway. Edit $AS_HOME/domains/domain1/domain.xml. Within the section of <jvm-options> tags, enter the following configuration item to ensure that log4j.properties file is referenced by Glassfish


<jvm-options>-Dlog4j.configuration=file:$AS_HOME/domains/domain1/config/log4j.properties</jvm-options>

To help limit the amount of log messages generated by c3p0 during access to the MySQL database, edit the $NHINC_PROPERTIES_DIR/log4j.properties file to add the following line: log4j.appender.com.mchange.v2.c3p0=WARN Copy the properties file into the Glassfish configuration directory for access at runtime. cp $NHINC_PROPERTIES_DIR/log4j.properties $AS_HOME/domains/domain1/config/.

This completes the installation and configuration of the NHIN CONNECT Gateway System. The next step for the installer is to verify the installation. Run the Soap UI Self Tests to ensure the installation was successful.

http://www.connectopensource.org/display/NHINR21/SoapUI+Tests

NOTE: We have experienced the soapUI default installation has the setting for the HTTP Version set incorrectly. If you experience any connectivity issues executing the soapUI tests, verify that the HTTP Version is set to 1.1 from the dropdown from File->Preferences HTTP Settings tab.

This is a known runtime WARNING message that is generated that can be ignored. The message is similar to

#|2009-05-14T11:36:31.979-0700|WARNING|sun-appserver9.1|javax.enterprise.system.stream.err|_ThreadID=52;_ThreadName=BPELSEInOutThread4;Process Instance Id=10.20.40.33:-165ac5b7:1214066bc08:-7fdf;Service Assembly Name=EntityCA;BPEL Process Name=PatientCorrelationFacadeBpel;_RequestID=132b49c0-e2f4-42cc-80f8-1e95317dcbbf;| java.util.logging.ErrorManager: 5: Error in extracting Name Value Pairs|#]

[#|2009-05-14T11:36:31.979-0700|WARNING|sun-appserver9.1|javax.enterprise.system.stream.err|_ThreadID=52;_ThreadName=BPELSEInOutThread4;Process Instance Id=10.20.40.33:-165ac5b7:1214066bc08:-7fdf;Service Assembly Name=EntityCA;BPEL Process Name=PatientCorrelationFacadeBpel;_RequestID=132b49c0-e2f4-42cc-80f8-1e95317dcbbf;| java.lang.NullPointerException


10.0 ACRONYMS

CA Certificate Authority

CAC Common Access Card

CD Compact Disk

CDC Centers for Disease Control & Prevention

CMS Centers for Medicare & Medicaid Services

DAT Digital Audio Tape

DOD Department of Defense

DURSA Data Use and Reciprocal Support Agreement

DVD Digital Video Disc

EHR Electronic Health Record

EMR Electronic Medical Record

ESB Enterprise Service Bus

FHA Federal Health Architecture

GB Gigabyte

HDD Hard Disk Drive

HITSP Healthcare Information Technology Standards Panel

IDE Integrated Drive Electronics

IHS Indian Health Services

IPv6 Internet Protocol Version 6

MB Megabyte

MPI Master Patient Index

NCI National Cancer Institute

NDMS National Disaster Medical System

NHIE NHIN Health Information Exchange

NHIN Nationwide Health Information Network

NIST National Institute of Standards and Technology

OID Object Identifier or Home Community ID

ONC Office of the National Coordinator

OS Operating System

QA Quality Assurance


RAID Redundant Array of Inexpensive Disks

RAM Random Access Memory

SCSI Small Computer System Interface

SDK Software Development Kit

SSA Social Security Administration

SSL Secure Sockets Layer

TBD To Be Determined

USB Universal Serial Bus

VA Department of Veterans Affairs

CONNECT_Solaris_Full_Binary_Manual A-1 Release 2.1 7/7/09

APPENDIX A


A. OID REQUEST SUBMITTAL PROCESS

A.1 Getting Started

Before you can request the OID, there are a few questions that you should answer. These answers will be requested during the OID request process.

• Your Main Point of Contact (POC): (This can be a project manager or a Technical point of contact)

• Your POC’s office address:

• Your POC’s phone number:

• Your POC’s fax number:

• Your POC’s Title:

• Organization’s url:

A.2 Submitting the Request

1. Login into: http://www.hl7.org/oid/index.cfm

Figure A.2-1: HL7-OID Registration Home Page


2. Select the “Click to Obtain or Register an OID” Hyperlink.

Figure A.2-2: Complete Contact Information

3. Complete the form as shown above including the information collected from Section A.1 of this document

a. The POC from section A.1 is your Contact Person and Responsible Body. It may also be the Submitter but the individuals do not have to be the same person.

b. Please make sure to add “http://” prior to the url information otherwise the OID request will error.

c. Resp Body Type select “Government body” from the drop down.

d. Once all the pertinent information is entered select the “Continue” button.


Figure A.2-3: Select type of OID

4. Leave the default as shown and select the “Next” button.


Figure A.2-4: New or Existing OID Designation

5. Select the first radio button and then select the “Next” button.

Figure A.2-5: HL7 OID Description

6. Add the Submitter contact information, enter the name of the server and provide a minor description.

a. Please note that the user can search by “Object Description” to locate the OID information. So you may want to provide a description that is significant to your organization.

b. Type of OID= 3.

c. Select the “Request my OID” button.


Figure A.2-6: OID Registration Confirmation

7. An acknowledgement of the submittal is displayed on the screen with the OID that as been generated. Please make note of the OID. Select the “Back” button to return to the first screen.

Figure A.2-7: OID Email Confirmation


8. An email detailing the request will also be sent to the Submitter and the Responsible Body.


A.3 Searching for an OID on the site

Figure A.3-1: Searching by OID number

1. The user can search by the OID number. The OID number that was generated or registered on this site is entered in the left panel in the “Enter the OID:” box and then the “Find OID” is selected. The right hand panel will display a drop down with results that match the criteria entered. The user can then select from the drop down the desired results and the “Submit” button for the details.

a. Please note that if the OID that you seek is not in the drop down, it may not have been registered or obtained from this site.


Figure A.3-2: Search by OID Description

2. The user can search by the OID description. The OID description that was entered during the generation process on this site is entered in the left panel in the “Enter a string to search the OID description:” box, and then the “Find OID” is selected. The right hand panel will display a drop down with results that match the criteria entered. The user can then select from the drop down the desired results and the “Submit” button for the details.