Version History

Version	Date	Modified By	Description of Modification
1.0	12/09/2016	Sovann Huynh	Initial version
1.1	02/01/2017	Minh-Hai Nguyen	Update JCE installation
1.2	02/24/2017	Sovann Huynh	Changed default config file to standalone-full.xml
1.3	10/25/18	Tabassum Jafri	Updated jboss_quick_setup.zip and certificate keysize to 2048
1.4	5/31/19	Eric McDonald	Corrected forum link and corrected a typo

Introduction

As of CONNECT 5.0, JBoss AS is no longer supported. Please upgrade to JBoss EAP 7 if possible. JBoss EAP 7 can be downloaded from https://access.redhat.com/products/red-hat-jboss-enterprise-application-platform ← Red Hat log in required

This guide includes a Quick Setup section and a Detailed Setup section. The quick setup utilizes JBoss EAP 7 configuration files that have been pre-configured for CONNECT deployment. Following the CONNECT setup instructions will result in a fully-functioning test gateway that should not be used as a live production system.

Please refer to Adopters Implementation Guidelines to integrate CONNECT with your live web service components and to import genuine certificates issued by an authorized certificate authority before attempting transactions on a live exchange.

Prerequisites

JAVA 8 is required for JBoss EAP 7
Either a downloaded CONNECT binary distribution or a local CONNECT build
A running instance of MySQL - The CONNECT team uses version 5.1.73
If Direct will be deployed with CONNECT, the Java Cryptography Extension must be installed. Please see the Oracle JCE Documentation.
Set JBOSS_HOME as an environment variable with the path to your JBoss installation root and add the variable to your class path

Quick Setup

JBOSS_ROOT refers to the JBoss root install directory. Anywhere JBOSS_ROOT is used in this document, replace it with the actual JBoss root install directory
CONNECT_ROOT refers to the root directory of either your local CONNECT repository or your CONNECT binary zip file

Pre-configured files

Download jboss_quick_setup.zip for the pre-formatted JBoss EAP 7 configuration files required in this quick setup process

Configure JBoss EAP 7 for CONNECT deployment

Create the CONNECT properties directory:
- For Windows, create a JBOSS_ROOT/modules/system/layers/base/org/connectopensource/configuration/main folder (some folders may already exist, some will need to be created)
- For Linux, execute the following command: mkdir -p /JBOSS_ROOT/modules/system/layers/base/org/connectopensource/configuration/main (some directories may already exist, some will need to be created)
Copy jboss_quick_setup.zip→module.xml into the newly-created CONNECT properties directory

Copy the CONNECT configuration files to the CONNECT properties directory.

CONNECT configuration files

In the binary distribution, the CONNECT properties are located in CONNECT_ROOT/properties
If CONNECT was built from source, the CONNECT properties are located in CONNECT_ROOT/Product/Production/Common/Properties/src/main/resources

Copy the correct standalone configuration file (standalone.conf for LINUX, standalone.conf.bat for Windows) to JBOSS_ROOT/bin:
- For Windows, copy jboss_quick_setup.zip→windows/standalone.conf.bat to JBOSS_ROOT/bin
- For Linux, copy jboss_quick_setup.zip→linux/standalone.conf to JBOSS_ROOT/bin
Copy jboss_quick_setup.zip→standalone_full.xml to JBOSS_ROOT/standalone/configuration

Generate a self-signed certificate and create key stores and trust stores

Execute the following commands from the CONNECT properties directory (created in the first step) to create the keystores. To manage these files in another location be sure to make the necessary configuration updates listed /wiki/spaces/CONNECTWIKI/pages/10584180.

Deploying CONNECT from Binaries#certkeystore

Create and populate databases and tables

Download and copy mysql-connector-java-5.1.10.jar into the JBOSS_ROOT /standalone/deployments directory to install the MySQL JDBC driver.

Execute the following SQL scripts:

dropall.sql
nhincdb.sql
populateTestData.sql

Database scripts

In the binary distribution, the database scripts are located in CONNECT_ROOT/DBScripts/nhincdb
If CONNECT was built from source, the database scripts are located in CONNECT_ROOT/Product/DBScripts/nhincdb

Deploy CONNECT

Start the JBoss EAP 7 server and open the admin console
If you haven't done so, you'll be required to create a new user:
1. For Linux, execute the JBOSS_ROOT/add-user.sh script, follow the directions and then click Try Again in the admin console (may require server restart)
2. For Windows, execute the JBOSS_ROOT/add-user.bat script, follow the directions and then click Try Again in the admin console (may require server restart)
In the Admin Console, click the Deployments tab
In the left Nav panel, click Add next to Deployment
Choose Upload a new deployment click Next, click Choose File and browse to the CONNECT.ear file, click Next and then click Finish
Click the Enable button corresponding to the CONNECT ear file

CONNECT ear

In the binary distribution, the CONNECT ear is located in CONNECT_ROOT/CONNECT-JB7/<CONNECT_VERSION>
If CONNECT was built from source, the CONNECT ear is located in CONNECT_ROOT/Product/Production/Deploy/jboss7/target

Deploy the Admin GUI

To deploy the CONNECT Admin GUI, repeat steps 1-4 above substituting the Admin GUI war for the CONNECT ear

Note: The Admin GUI is optional but recommended for ease of CONNECT administration and can be downloaded from the /wiki/spaces/CONNECTWIKI/pages/117610137 page

Admin GUI war

If CONNECT was built from source, the Admin GUI war is located in CONNECT_ROOT/Product/Production/Adapters/General/CONNECTAdminGUI

If you are having trouble deploying CONNECT using the quick setup instructions, follow the detailed setup instructions below step by step or reference the information below to troubleshoot

Detailed Setup

CONNECT properties directory module setup - org.connectopensource

Create the JBOSS_ROOT/modules/system/layers/base/org/connectopensource/configuration/main directory

org.connectopensource module directory

mkdir -p JBOSS_ROOT/modules/system/layers/base/org/connectopensource/configuration/main

To register this as a JBoss module, create a module.xml file in this new folder and add the following contents:

${JBOSS_HOME}/modules/org/connectopensource/configuration/main/module.xml

<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.1" name="org.connectopensource.configuration">
    <resources>
        <resource-root path="."/>
    </resources>
</module>

Copy/transfer the CONNECT configuration files to the org.connectopensource module directory. In the binary distribution, these files can be found in the Properties directory. To copy directly from the source:

cp -r ${CONNECT_ROOT}/Product/Production/Common/Properties/src/main/resources/* JBOSS_ROOT/modules/system/layers/base/org/connectopensource/configuration/main

These following instructions create and configure keystores and truststores on the JBoss classpath. To manage these files in another location be sure to make the necessary configuration updates listed /wiki/spaces/CONNECTWIKI/pages/10584180.

Create the keystores in the org.connectopensource module directory:

keytool -v -genkey -keyalg RSA -keysize 2048 -keystore gateway.jks -keypass changeit -storepass changeit -validity 365 -alias gateway -dname "cn=localhost"
keytool -v -export -rfc -alias gateway -file localhost.cer -keystore gateway.jks -keypass changeit -storepass changeit
keytool -v -import -keypass changeit -noprompt -trustcacerts -alias localhost -file localhost.cer -keystore cacerts.jks -storepass changeit

Setting JAVA_OPTS

In the standalone configuration file (JBOSS_ROOT/bin/standalone.conf in Linux, JBOSS_ROOT/bin/standalone.conf.bat in Windows), append the following and localize each statement based on your target OS:

standalone.conf for Linux

# Use standalone-full.xml instead of standalone.xml
JAVA_OPTS="$JAVA_OPTS  -Djboss.server.default.config=standalone-full.xml"

# Increase memory allocation
JAVA_OPTS="$JAVA_OPTS -Xmx8000m"

# configuration directory
JAVA_OPTS="$JAVA_OPTS -Dnhinc.properties.dir=$JBOSS_HOME/modules/system/layers/base/org/connectopensource/configuration/main"

# keystore and truststore
JAVA_OPTS="$JAVA_OPTS -Djavax.net.ssl.keyStore=$JBOSS_HOME/modules/system/layers/base/org/connectopensource/configuration/main/gateway.jks"
JAVA_OPTS="$JAVA_OPTS -Djavax.net.ssl.keyStorePassword=changeit"
JAVA_OPTS="$JAVA_OPTS -Djavax.net.ssl.keyStoreType=JKS"
JAVA_OPTS="$JAVA_OPTS -Djavax.net.ssl.trustStore=$JBOSS_HOME/modules/system/layers/base/org/connectopensource/configuration/main/cacerts.jks"
JAVA_OPTS="$JAVA_OPTS -Djavax.net.ssl.trustStorePassword=changeit"
JAVA_OPTS="$JAVA_OPTS -Djavax.net.ssl.trustStoreType=JKS"
JAVA_OPTS="$JAVA_OPTS -DCLIENT_KEY_ALIAS=gateway"

standalone.conf.bat for Windows

rem # Use standalone-full.xml instead of standalone.xml
set "JAVA_OPTS=%JAVA_OPTS% -Djboss.server.default.config=standalone-full.xml"

rem # Increase memory allocation
set "JAVA_OPTS=%JAVA_OPTS% -Xmx8000m"

rem # CONNECT configuration directory
set "JAVA_OPTS=%JAVA_OPTS% -Dnhinc.properties.dir=%JBOSS_HOME%/modules/system/layers/base/org/connectopensource/configuration/main"

rem # keystore and truststore
set "JAVA_OPTS=%JAVA_OPTS% -Djavax.net.ssl.keyStorePassword=changeit"
set "JAVA_OPTS=%JAVA_OPTS% -Djavax.net.ssl.trustStorePassword=changeit"
set "JAVA_OPTS=%JAVA_OPTS% -Djavax.net.ssl.keyStore=%JBOSS_HOME%/modules/system/layers/base/org/connectopensource/configuration/main/gateway.jks"
set "JAVA_OPTS=%JAVA_OPTS% -Djavax.net.ssl.keyStoreType=JKS"
set "JAVA_OPTS=%JAVA_OPTS% -Djavax.net.ssl.trustStoreType=JKS"
set "JAVA_OPTS=%JAVA_OPTS% -Djavax.net.ssl.trustStore=%JBOSS_HOME%/modules/system/layers/base/org/connectopensource/configuration/main/cacerts.jks"
set "JAVA_OPTS=%JAVA_OPTS% -DCLIENT_KEY_ALIAS=gateway"
set "JAVA_OPTS=%JAVA_OPTS% -Dcom.sun.xml.ws.transport.http.HttpAdapter.dump=true"
set "JAVA_OPTS=%JAVA_OPTS% -Dcom.sun.xml.ws.transport.http.client.HttpTransportPipe.dump=true"

Configure SSL

Make the following configuration changes in standalone-full.xml:

Add a connect socket binding for port 8181 under the "standard-sockets" socket binding group

standalone-full.xml

<socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">
    ...
    <socket-binding name="connect" port="8181"/>
    ...
</socket-binding-group>

Add an HTTPS listener to the "default-server" entry in the Undertow subsystem:

standalone-full.xml

<subsystem xmlns="urn:jboss:domain:undertow:3.1">
    ...
    <server name="default-server">
        ...
        <https-listener name="https" socket-binding="connect" security-realm="ApplicationRealm" verify-client="REQUIRED"/>
        ...
    </server>
    ...
</subsystem>

Under the ApplicationRealm security realm, update the authentication to reference your truststore, and add a server identity to reference your keystore:

standalone-full.xml

<security-realm name="ApplicationRealm">
    <server-identities>
        <ssl>
            <keystore path="modules/system/layers/base/org/connectopensource/configuration/main/gateway.jks"
                      relative-to="jboss.home.dir"
                      keystore-password="changeit"
                      alias="gateway"/>
        </ssl>
    </server-identities>
    <authentication>
        <truststore path="modules/system/layers/base/org/connectopensource/configuration/main/cacerts.jks"
                    relative-to="jboss.home.dir"
                    keystore-password="changeit"/>
        ...
    </authentication>
	...
</security-realm>

Address Bindings

By default, JBoss EAP services and applications are bound only to localhost. As needed, change any references of 127.0.0.1 in standalone-full.xml to the desired binding address. 0.0.0.0 can be used to bind to all addresses.

Configure Data Sources

Copy the mysql-connector-java-5.1.10.jar into the JBOSS_ROOT/standalone/deployments directory to install the MySQL JDBC driver.

Browse to http://localhost:9990 to open up the Admin Console. Click on Configuration->Subsystems->Data Sources->Non-XA. Click on Add and use the following chart to configure your data sources (make sure you select the MySQL JDBC driver and provide database username and password):

Name	JNDI Name	Connection URL	Ref-Name	JTA
adminguidb_pool	java:/jdbc/adminguidb_datasource	jdbc:mysql://localhost:3306/adminguidb	jdbc/adminguidb_datasource	true
assigningauthoritydb_pool	java:/jdbc/assigningauthoritydb_datasource	jdbc:mysql://localhost:3306/assigningauthoritydb	jdbc/assigningauthoritydb_datasource	true
asyncmsgs_pool	java:/jdbc/asyncmsgs_datasource	jdbc:mysql://localhost:3306/asyncmsgs	jdbc/asyncmsgs_datasource	true
auditrepo_pool	java:/jdbc/auditrepo_datasource	jdbc:mysql://localhost:3306/auditrepo	jdbc/auditrepo_datasource	false
configdb_pool	java:/jdbc/configdb_datasource	jdbc:mysql://localhost:3306/configdb	jdbc/configdb_datasource	true
docrepository_pool	java:/jdbc/docrepository_datasource	jdbc:mysql://localhost:3306/docrepository	jdbc/docrepository_datasource	true
eventdb_pool	java:/jdbc/eventdb_datasource	jdbc:mysql://localhost:3306/eventdb	jdbc/eventdb_datasource	true
messagemonitoringdb_pool	java:/jdbc/messagemonitoringdb_datasource	jdbc:mysql://localhost:3306/messagemonitoringdb	jdbc/messagemonitoringdb_datasource	true
patientcorrelationdb_pool	java:/jdbc/patientcorrelationdb_datasource	jdbc:mysql://localhost:3306/patientcorrelationdb	jdbc/patientcorrelationdb_datasource	true
patientdb_pool	java:/jdbc/patientdb_datasource	jdbc:mysql://localhost:3306/patientdb	jdbc/patientdb_datasource	true
transrepo_pool	java:/jdbc/transrepo_datasource	jdbc:mysql://localhost:3306/transrepo	jdbc/transrepo_datasource	true

Enable the data sources

The data sources need to be enabled after they have been added. An additional optional step would be to test all the connections after enabling.

Deploy CONNECT

In the Admin Console, click Deployments tab

In the left Nav panel, click Add next to Deployment

Choose Upload a new deployment click Next, click Choose File and browse to the <binary-location>/CONNECT-<VERSION>/CONNECT/<VERSION>/CONNECT-JB7-<VERSION>.ear file, click Next and then click Finish

Click the Enable button corresponding to the CONNECT ear file

Optional: For deploying CONNECT Admin GUI, repeat the steps 1-4 using <binary-location>/CONNECT-<VERSION>/CONNECTAdminGU/<VERSION>/CONNECTAdminGUI-<VERSION>.war.

Log4J Configuration

Edit $JBOSS_HOME/standalone/configuration/standalone-full.xml as following:

Add new file handler (ie NHIN) under the existing File handler to logging subsystem:

logging subsystem

<subsystem xmlns="urn:jboss:domain:logging:3.0">
...
<periodic-rotating-file-handler name="NHIN" autoflush="true">
  <formatter>
    <named-formatter name="PATTERN"/>
  </formatter>
  <file relative-to="jboss.server.log.dir" path="NHIN.log"/>
  <suffix value=".yyyy-MM-dd"/>
  <append value="true"/>
</periodic-rotating-file-handler>
<logger category="gov.hhs">
  <level name="DEBUG"/>
  <handlers>
    <handler name="NHIN"/>
  </handlers>
</logger>
...
</subsystem>

FIPS Mode

JBoss EAP 7 with FIPS 140-2 Configuration

Links / Additional Reading

CONNECT Forums

JBOSS EAP 7 Documentation

Browser not supported