CONNECT Dynamic Document Installation and Configuration Manual

Version 1.0 CONNECT Release 2.4 18 March 2010

REVISION HISTORY REVISION 1.0 DATE 18 March 2010 DESCRIPTION Initial Release

CONNECT_Dynamic_Document 03/18/10

Release 2.4

TABLE OF CONTENTS 1.0 INTRODUCTION ......................................................................................... 1 1.1 PURPOSE ........................................................................................................... 1 1.2 SCOPE ............................................................................................................... 2 2.0 INSTALLATION CHECKLIST ..................................................................... 2 3.0 INSTALLATION OF DYNAMIC DOCUMENT COMPONENTS................... 2 4.0 DATABASE CONFIGURATION.................................................................. 2 4.1 CONFIGURATION OF DOMAIN.XML .......................................................................... 3 4.2 CONFIGURE DYNAMIC DOCUMENT COMPONENT ENDPOINTS ................................... 6 4.3 CONFIGURATION OF PROPERTY FILES ................................................................... 7 4.3.1 $NHINC_PROPERTIES_DIR/adapter_common_datalayer.properties. ........ 7 4.3.2 $NHINC_PROPERTIES_DIR/repository.properties ...................................... 8 4.3.3 $NHINC_PROPERTIES_DIR/Hibernate/dyndocrepo.hibernate.cfg.xml ....... 8 4.3.4 $NHINC_PROPERTIES_DIR/CAL_Emulator/xml/*.xml ................................ 8 4.4 RESTARTING GLASSFISH AND VERIFICATION OF CONFIGURATION ............................ 9 4.5 DEPLOY DYNAMIC DOCUMENT GENERATION EJBS............................................... 10 4.6 EXECUTE SOAPUI TESTS ................................................................................... 11

LIST OF FIGURES FIGURE 4.4-1 FIGURE 4.5-1 FIGURE 4.5-2 FIGURE 4.6-1 VERIFY CONFIGURATION ............................................................................... 9 SELECT EJB MODULES .............................................................................. 10 DEPLOY COMPONENTS ............................................................................... 11 VIEW TEST CASES ..................................................................................... 12

CONNECT_Dynamic_Document 03/18/10

ii

Release 2.4

1.0 1.1

INTRODUCTION Purpose

This document is the installation and configuration manual for installing the Dynamic Document components. These adapter components are independent components to replace the reference adapter side components delivered with CONNECT. The Dynamic Document generation components were generated by Telemedicine & Advanced Technology Research Center and Northrop Group Corporation in support of the DoD/VLER Phase 1a Pilot demonstration. The FHA has taken this contribution and incorporated the Dynamic Document generation portion into CONNECT R2.4. In general, the process flows as follows: 1. A Document Query request is received by the adapter. 2. Document Assembly validates with the Templates Manager that the requested document is supported. Upon successful validation of the document type, Document Assembly validates that the patient exists in the system. 3. Upon successful validation of the patient, the Document Query request is passed to the CDA Document Builder component. 4. CDA Document Builder requests templates information from Templates Manager for the requested document. For example, when the requested document is a C32 document, the Templates Manager will respond with a list of CDA sections, such as Patient Information, Allergies, Medications and so on, that constitute a C32 document. 5. CDA Document Builder then makes a request to the CDA Sections Assembler to get the necessary sections in order to construct the requested document. 6. CDA Sections Assembler requests templates information from the Templates Manager for the requested section. For example, when the requested section is a Problem List, the Templates Manager will respond with a list of one CDA Condition module. 7. CDA Sections Builder makes a request to the CDA Modules Assembler to obtain the necessary modules in order to construct a CDA section in accordance with the HITSP/C83 CDA Content Modules Specification. 8. CDA Modules Assembler makes request(s) to the Data Access Service to obtain contents for the module's data elements and construct a CDA module in accordance with the HITSP/C83 CDA Content Modules Specification. 9. Document Assembly returns the document to the calling entity.

CONNECT_Dynamic_Document 03/18/10

Release 2.4

1.2

Scope

The procedures in this document are specific to the installation of the Adapter Dynamic Document Generation components on a Windows Operating System. 2.0 INSTALLATION CHECKLIST

The installation of the Dynamic Document components assumes the successful completion of the CONNECT System Installation and Configuration procedure: http://developer.connectopensource.org/display/NHINR24/Release+2.4+Home The following steps are required to complete the installation and configuration. Item 1 2 3 4 5 6 7 3.0 Procedural Step Install the Dynamic Document Generation components Configure the Glassfish domain.xml to support Dynamic Document Generation databases Update internalConnectionInfo.xml to include endpoints for Dynamic Document Generation components. Configure properties files Restart Glassfish and Verify configuration Deploy Dynamic Document Generation EJBs Execute default CONNECT SoapUI Tests INSTALLATION OF DYNAMIC DOCUMENT COMPONENTS

There are five EJB components that comprise the Dynamic Document Generation functionality. These components are available in the NHIN_CONNECT_DynamicDocuments_2.4.0.xxx.zip file where xxx is the release build number. Extract the components into C:\temp. This will create the C:\temp\bin directory that contains the components. The deployment of these components is detailed in section 4.0 DATABASE CONFIGURATION

The Dynamic Document Generation capabilities utilize Toplink and Hibernate database drivers to access MySQL database tables in support of generating dynamic documents. The existing database schema docrepository is altered in support of this feature, and additional database schemas and tables are created. The database scripts are provided in the delivery in NHIN_CONNECT_Binaries_2.4.0.xxx.zip. Explode the zip file into CONNECT_Dynamic_Document 03/18/10 2 Release 2.4

C:\temp. The database scripts to support dynamic document generation are located in DBScripts\dynamicdocuments. The existing CONNECT system user nhincuser/nhincpass is used in support of Dynamic Document database access. The following steps assume that the MySQL installation resides at C:\Program Files\MySQL\MySQL Server 5.1\bin. Otherwise, use the directory path to MySQL that applies to the target environment. cd C:\Program Files\MySQL\MySQL Server 5.1\bin mysql uroot pNHIE-Gateway <c:\temp\DBScripts\dynamicdocuments\docrepository_dll.sql mysql uroot pNHIE-Gateway <c:\temp\DBScripts\dynamicdocuments \docassembly_dll.sql mysql uroot pNHIE-Gateway <c:\temp\DBScripts\dynamicdocuments \templatedb_dll.sql NOTE: During execution of the Dynamic Document components, the altering of the docrespository tables takes place. Due to this alteration to the table schema, once the Dynamic Documentation components are executed on a CONNECT system, the docrepository schema should be regenerated to recreate the reference version to be compatible with the reference copy of the DocumentRepositoryEJB. 4.1 Configuration of domain.xml

Confirm that the Glassfish application server is stopped using the following command from the DOS command line: asadmin stop-domain domain1 Edit the domain.xml for the Glassfish application server. The Dynamic Document Generation components use the database connection pools that are defined/configured in the domain.xml file. Add the following statements: <jdbc-resource enabled="true" jndi-name="jdbc/dasDS" object-type="user" pool-name="docassemblyPool"/> <jdbc-resource enabled="true" jndi-name="jdbc/templateDS" object-type="user" pool-name="templatedbPool"/>

CONNECT_Dynamic_Document 03/18/10

Release 2.4

Add <jdbc-connection-pool> tags, which describe the connection pools referenced in the <jdbc-resource> tags. <jdbc-connection-pool allow-non-component-callers="true" associate-with-thread="false" connection-creation-retry-attempts="0" connection-creation-retry-interval-in-seconds="10" connection-leak-reclaim="false" connection-leak-timeout-in-seconds="0" connection-validation-method="auto-commit" datasourceclassname="com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSou rce" fail-all-connections="true" idle-timeout-in-seconds="300" is-connection-validation-required="true" is-isolation-level-guaranteed="false" lazy-connection-association="false" lazy-connection-enlistment="false" match-connections="false" max-connection-usage-count="0" max-pool-size="5" max-wait-time-in-millis="600000" name="docassemblyPool" non-transactional-connections="true" pool-resize-quantity="1" res-type="javax.sql.ConnectionPoolDataSource" statement-timeout-in-seconds="-1" steady-pool-size="3" validate-atmost-once-period-in-seconds="0" wrap-jdbc-objects="false"> <description>Connection pool for docassembly schema</description> <property name="MaxRows" value="-1"/> <property name="DriverClass" value="com.mysql.jdbc.Driver"/> <property name="PortNumber" value="3306"/> <property name="Password" value="nhincpass"/> <property name="LoginTimeout" value="0"/> <property name="User" value="nhincuser"/> CONNECT_Dynamic_Document 03/18/10 4 Release 2.4

<property name="URL" value="jdbc:mysql://localhost:3306/docassembly"/> <property name="ServerName" value="localhost"/> </jdbc-connection-pool> <jdbc-connection-pool allow-non-component-callers="true" associate-with-thread="false" connection-creation-retry-attempts="0" connection-creation-retry-interval-in-seconds="10" connection-leak-reclaim="false" connection-leak-timeout-in-seconds="0" connection-validation-method="auto-commit" datasourceclassname="com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSou rce" fail-all-connections="true" idle-timeout-in-seconds="300" is-connection-validation-required="true" is-isolation-level-guaranteed="false" lazy-connection-association="false" lazy-connection-enlistment="false" match-connections="false" max-connection-usage-count="0" max-pool-size="5" max-wait-time-in-millis="600000" name="templatedbPool" non-transactional-connections="true" pool-resize-quantity="1" res-type="javax.sql.ConnectionPoolDataSource" statement-timeout-in-seconds="-1" steady-pool-size="3" validate-atmost-once-period-in-seconds="0" wrap-jdbc-objects="false"> <description>Connection pool for templates schema</description> <property name="MaxRows" value="-1"/> <property name="DriverClass" value="com.mysql.jdbc.Driver"/> <property name="PortNumber" value="3306"/> CONNECT_Dynamic_Document 03/18/10 5 Release 2.4

<property name="Password" value="nhincpass"/> <property name="LoginTimeout" value="0"/> <property name="User" value="nhincuser"/> <property name="URL" value="jdbc:mysql://localhost:3306/templatedb"/> <property name="ServerName" value="localhost"/> </jdbc-connection-pool>

Add <resource-ref> tags to the <server> node, then enter the following reference tags to ensure that the connection resources are available to the adapter components. < resource-ref enabled="true" ref="jdbc/dasDS"/> < resource-ref enabled="true" ref="jdbc/templateDS"/> 4.2 Configure Dynamic Document Component Endpoints in the

The Dynamic Document component endpoints are defined internalConnectionInfo.xml. The following endpoints need to be updated:

<service> <name>adapterdocquerysecured</name> <description>Adapter Document Query</description> <endpointURL>https://localhost:8181/NhinConnect/AdapterDocQuerySec ured</endpointURL> </service> <service> <name>adapterdocretrievesecured</name> <description>Adapter Document Retrieve Secured</description> <endpointURL>https://localhost:8181/NhinConnect/AdapterDocRetrieveS ecured</endpointURL> </service> <service> <name>adapterxdsbdocrepository</name> <description>Adapter Document Repository</description> <endpointURL>http://localhost:8080/DocumentRepository/DocumentRepo sitory_Service</endpointURL> </service> <service> CONNECT_Dynamic_Document 03/18/10 6 Release 2.4

<name>adapterxdsbdocregistry</name> <description>Adapter Document Registry</description> <endpointURL>http://localhost:8080/DocumentRegistry/DocumentRegistry _Service</endpointURL> </service> The following endpoints need to be added: <service> <name>adaptercommondatalayerservice</name> <description>Adapter Common Data Layer Service</description> <endpointURL>http://localhost:8080/DoDConnectorService/DoDConnecto rService</endpointURL> </service> <service> <name>documentassembly</name> <description>Adapter Document Assembly Service</description> <endpointURL>http://localhost:8080/DocumentAssembly/AdapterDocume ntAssembly</endpointURL> </service> <service> <name>documentmanager</name> <description>Adapter Document Manager</description> <endpointURL>http://localhost:8080/DocumentManager_Service/Docume ntManagerService</endpointURL> </service> 4.3 Configuration of Property Files

The Dynamic Document configuration is controlled by several property files. Each of the property files are described in the following sections. They are delivered with the database scripts in NHIN_CONNECT_Binaries_2.4.0.xxx.zip. 4.3.1 $NHINC_PROPERTIES_DIR/adapter_common_datalayer.properties. This property file contains the configuration properties for common data layer components. The directory path to the CAL_Emulator files is specified here as well as the flags to enable/disable access to the emulator files for Dynamic Document data. Common Access Layer (CAL) data files contain the dynamic data used in the dynamic generation of documents. The default location is $NHINC_PROPERTIES_DIR\CAL_Emulator\xml. The data files that are located here are the C32 message components user during dynamic document generation to

CONNECT_Dynamic_Document 03/18/10

Release 2.4

emulate an interface to a specific HER system. To enable the emulation, set the *_test flags to Y. medications_test=Y allergies_test=Y problems_test=Y patient_info_test=Y

4.3.2 $NHINC_PROPERTIES_DIR/repository.properties This property file contains the default repository id used by the AdapterDocumentRepositoryEJB when storing generated documents in the repository. The repositoryId is used by the DocumentManagerEJB. For this version of the Dynamic Document Generation, the policyRespositryId and the inboundDocumentRepositoryId are not currently used. The documentUniqueOID is used when creating a document unique id. 4.3.3 $NHINC_PROPERTIES_DIR/Hibernate/dyndocrepo.hibernate.cfg.xml This file contains the Hibernate configuration for the document repository. The Dynamic Document Generation feature uses an altered version of the reference docrepository database table provided with CONNECT. There are no configuration modifications required on this property file. 4.3.4 $NHINC_PROPERTIES_DIR/CAL_Emulator/xml/*.xml These are the support data files used for Dynamic Document Generation. These files are stubs to be replaced by an Adapter Agencys specific interface to patient records. These are a set of files with the following naming conventions: <receiverOID>_<patientID>_ALLERGIES_CareRecordQUOCIN043200UV01Res ponse.xml <receiverOID>_<patientID>_PATIENT_INFO_PatientDemographicsPRPAMT201 303UV02Response.xml <receiverOID>_<patientID>_MEDS_CareRecordQUOCIN043200UV01Response .xml <receiverOID>_<patientID>_PROBLEMS_CareRecordQUOCIN043200UV01Res ponse.xml

CONNECT_Dynamic_Document 03/18/10

Release 2.4

These files can be modified to change the default set of patient health record information to return from Dynamic Document Generation. The modifications are then incorporated into the document and accessible in the repository. Medications, allergies, problems, and patient info can be changes in these files and the results present in the next dynamic document generated. 4.4 Restarting Glassfish and Verification of Configuration

Perform the following steps to restart the Glassfish application and verify the configuration: 1. Restart Glassfish by executing asadmin start-domain domain1. 2. Verify that the connection pools are defined from the Glassfish console. You will need to first log on to the Glassfish admin console. 3. 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. 4. Select the Resources task from the navigation panel on the left. 5. Expand out the JDBC node. Then expand the JDBC Resources to verify the jdbc/dasDS and jdbc/templateDS are defined. 6. Expand the Connection Pools to verify the docassemblyPool and templatedbPool are defined.

Figure 4.4-1 Verify Configuration CONNECT_Dynamic_Document 03/18/10 9 Release 2.4

4.5

Deploy Dynamic Document Generation EJBs

The Dynamic Document Generation functionality is provided through five EJBs. The component below is a replacement for the reference version provided with the default CONNECT installation: DocumentRepositoryEJB is replaced with AdapterDocumentRepositoryEJB

The complete list of the EJBs to be deployed is as follows: AdapterCommonDataLayerEJB AdapterDocumentAssemblyProxyEJB AdapterDocumentRepositoryEJB DocumentManagerEJB NhinAdapterServiceEJB Each of these EJBs is deployed manually from the Glassfish console by executing the following steps for each component. 1. From the Glassfish console, select EJB Modules from the navigation panel on the left.

Figure 4.5-1 Select EJB Modules CONNECT_Dynamic_Document 03/18/10 10 Release 2.4

2. Select the Deploy button. From this page, you can select the Browse button to navigate to each of the Dynamic Document components to be deployed. Then select the OK button to initiate the deployment.

Figure 4.5-2 Deploy Components 3. Follow these same steps for each of the five EJBs listed above. Then stop/start Glassfish via: asadmin stop-domain domain1 asadmin start-domain domain1 4. Monitor the server.log to verify a clean/successful restart. 4.6 Execute SoapUI Tests

The CONNECT System comes with a set of SoapUI tests to execute the core system using a reference version of the adapter components. The SoapUI tests for Dynamic Document Generation are included with these tests with the tests cases in a default

CONNECT_Dynamic_Document 03/18/10

11

Release 2.4

disable state. The tests are called Dynamic Document Query and Dynamic Document Retrieve. NOTE: When the CONNECT System is in the Dynamic Document Generation configuration, the default Document Query and Document Retrieve SoapUI tests will fail to execute successfully. After launching the SoapUI GUI and loading the DynamicDocumentTest-Internalsoapui-project.xml and DynamicDocumentTest-EndtoEnd-soapui-project.xml from C:\Temp\SelfTest\DynamicDocumentTest, expand the test suite nodes to view the individual test cases. By default, the dynamic versions of Document Query and Document Retrieve may have disabled. Prior to running the tests, the dynamic test cases have to be enabled.

Figure 4.6-1 View Test Cases The tests can be run as a suite or individually. The only test case applicable to Dynamic Document Generation is the Dynamic Document Query and Dynamic Document Retrieve tests. CONNECT_Dynamic_Document 03/18/10 12 Release 2.4