Installation Instructions

Overview of the Architecture of the Integration

In this page we provide you with instructions on how to install OpenEMPI as the Enterprise Master Patient Index within the NHIN CONNECT Gateway. Currently OpenEMPI supports deployment within Connect Gateway versions 3.x (we have tested the integration with 3.0, 3.1, 3.2 and 3.2.1). The instructions also make the assumption that that you have already successfully installed the CONNECT Gateway and have passed the tests and that you already have installed an instance of OpenEMPI successfully.

There are two parts to the installation of OpenEMPI within CONNECT:

The adapter for OpenEMPI is the component that provides the integration between an OpenEMPI instance and a CONNECT Gateway instance. It is encapsulated into a web application and exposes a web service that implements the MPI interface as defined by the NwHIN specifications. The web application is released in the form of a war file and can be deployed on any web container although the instructions assume that you are using JBoss. We have tested it with both Tomcat and Glassfish as well and did not run into any issues.
A proxy component is deployed along with CONNECT on the Glassfish instance that is hosting CONNECT. The proxy service simply redirects requests to the Tomcat instance that is hosting the adapter.

The figure below shows a graphical depiction of the architecture of the integration of OpenEMPI into the NwHIN CONNECT Gateway. The NHIN CONNECT Gateway is deployed on a Glassfish server which is the default deployment platform currently although other applications are supported to varying degrees. The green rectangles represent individual services that comprise the NwHIN Connect Gateway SOA-based architecture. One of those services is the openempi-nhin-proxy service which behaves like a proxy and redirects requests to the actual OpenEMPI NHIN adapter. The adapter is deployed on a Tomcat instance, which by default and for security reasons is assumed to be hosted on the same server as the NHIN Gateway (or its adapter layer at least).

Installation Steps

The deployment package for OpenEMPI includes two components that comprise the integration with the CONNECT gateway. Select the appropriate package for your platform and download the latest release to the server that has the gateway installed. The release package is either openempi-2.2.x-openempi.tar.gz or openempi-2.2.x-openempi.zip. Extract the contents in a directory of your preference. The instruction will assume that you extracted the contents of the package into the /nhin directory so the contents of the package will reside in /nhin/openempi-2.2.x. The two cmponents that provide the integration with the CONNECT gateway are:

A jar file called openempi-nhin-proxy-2.2.x.jar that comprises the OpenEMPI proxy, which will be deployed along the CONNECT software installation, and serves the purpose described in the previous section.
A war file called openempi-nhin-adapter-2.2.x.war that comprises the OpenEMPI adapter. The adapter gets deployed on a web container although we assume that you are using JBoss 4.2.3 for the purpose of the instructions.

1. The first step is the installation of the NHIN adapter. You can deploy the adapter on any web container although we assume that you are using JBoss 4.2.3 in the instructions. You can install the JBoss server in the /nhin directory although you can place it anywhere you have space. Before deploying the war file, setup an environment variable called OPENEMPI_HOME which points to the location where you extracted the contents of the OpenEMPI distribution. If you followed the recommendations of these instructions, the variable should be set to:

 export OPENEMPI_HOME=/nhin/openempi-2.2.0

 set OPENEMPI_HOME=c:/nhin/openempi-2.2.0

The JBoss server starts the web container listening on port 8080 by default. If you are installing JBoss on the same server that is running the CONNECT gateway then there is going to be a conflict because Glassfish listens on port 8080 by default. You can change the port on which JBoss listens to 8081 by modifying the file server/default/deploy/jboss-web.deployer/server.xml of the JBoss distribution. The relevant section from the configuration file is shown below:

 
    <Connector port="8081" address="${jboss.bind.address}"
         maxThreads="250" maxHttpHeaderSize="8192"
         emptySessionPath="true" protocol="HTTP/1.1"
         enableLookups="false" redirectPort="8443" acceptCount="100"
         connectionTimeout="20000" disableUploadTimeout="true" />

Once you have a running instance of the JBoss server, deploying the OpenEMPI adapter is as simple as copying the war file openempi-nhin-adapter-2.2.0.war to the server/default/deploy directory of the JBoss server. You can confirm that the application deployed properly by pointing your browser to the following URL:

 http://127.0.0.1:8081/openempi-nhin-adapter/

If you get the message "Hello World!" then everything worked properly so far.

2. The second step is the deployment of the OpenEMPI NHIN proxy on the Connect Gateway. Deploying the proxy is as simple as copying the openempi-nhin-proxy-2.2.0.jar file to the /nhin/SUNappserver/domains/domain1/lib directory. If the server was running when you copied the jar file, you will need to restart it for the change to take effect.

Once the proxy is deployed, we need to make two changes to the configuration of the Connection Manager in the Connect Gateway. The first change is modifying the endpoint for the AdapterComponentMpiService to be the OpenEMPI proxy service that we just deployed instead of the default MPI proxy implementation. The following section from the internalConnectionInfo.xml file shows the change that you need to make. We simply change the endpoint for component adaptercomponentmpiservice to point to the EJB service. The internalConnectionInfo.xml file that needs to be modified is usually stored under SUNWappserver/domains/domain1/config/nhin.

 
     <service>
        <name>adaptercomponentmpiservice</name>
        <description>Master Patient Index Component</description>
	<endpointURL>http://127.0.0.1:8081/openempi-nhin-adapter/AdapterComponentMpiService</endpointURL>
<!--        <endpointURL>http://localhost:8080/CONNECTAdapter/AdapterComponentMpiService</endpointURL>-->
      </service>

This URL is how the proxy locates the running instance of the OpenEMPI NHIN adapter so if you decide to use SSL or host the service on a different server or port, all you need to do is change the URL.

The second changes the endpoint that is used by default to service the patient discovery requests on the adapter layer. This is done by changing the Spring configuration file to point to the OpenEMPI proxy instead of one of the other alternative proxy implementations. The file is named AdapterComponentMpiProxyConfig.xml and it is located in the /nhin/SUNappserver/domains/domain1/config/nhin directory. The change is shown below:

 
	<bean class="org.openhie.openempi.nhinproxy.OpenempiAdapterComponentProxy" id="mpi" name="mpiopenempi"> 
		<meta key="impltype" value="java"/>
		<meta key="default" value="true"/>
	</bean> 
<!--
    <bean class="gov.hhs.fha.nhinc.mpi.adapter.component.proxy.AdapterComponentMpiProxyWebServiceSecuredImpl" id="mpi" name="mpiwssecured"> 
		<meta key="impltype" value="wssecured"/>
	</bean> 
  -->

Your Connect Gateway is now configured to use OpenEMPI as the EMPI internally. You could test the installation using SOAPUI tests that are included with the OpenEMPI You probably already have SOAPUI since it is used for testing the Connect Gateway installation, but if not you may download it from http://www.soapui.org/. You can run the tests using the test runner with the following command:

 ~/tools/soapui-3.0.1/bin/testrunner.sh OpenEmpiNhinAdapter-soapui-project.xml

If you run into any issues, please let us know by posting questions on the forum or raising issues.