Oracle® Healthcare Master Person Index Working With IHE Profiles Release 1.1 Part Number E18591-01 |
|
|
View PDF |
You need to configure the lifecyle modules for the application server you use. You also need to configure IHE-required application server resources, such as JDBC resources and JMS resources.
This chapter includes the following sections:
"Configuring GlassFish Enterprise Server v2.1.1 and Lifecycle Modules"
"Configuring Secure Web Services on GlassFish Enterprise Server v2.1.1"
For GlassFish Enterprise Server configuration information go to http://docs.sun.com/app/docs/doc/821-0185?l=en
to see the Sun GlassFish Enterprise Server v2.1.1 Administration Guide (Part No: 821-0185).
Lifecycle modules, which initiate at server start up, allow you to run Java-based tasks within a GlassFish Enterprise Server environment. When you use GlassFish, you need to install and configure one lifecycle module:
HL7V2 Server Lifecycle Module
Note:
You must install and configure both modules on the GlassFish Server before you can deploy the IHE EAR file.You can install the lifecycle modules from the command line or the admin console.
To install IHE HL7 v2 lifecycle module to your target application server, perform the following:
Unzip hl7v2.zip
to a directory of your choice (for example, your OHMPI installation directory. The unzipped hl7v2
directory is your HL7v2 server home).
Start your GlassFish server (if it is not already running).
Navigate to your GlassFish installation's bin
folder.
From the command prompt, run asadmin as
asadmin
create-lifecycle-module
--classname oracle.hsgbu.ohmpi.ihe.hl7v2.management.HL7ServiceGFManager
--classpath <your HL7 v2 server folder root
path>\lib\ihe-mpi-hl7v2-management.jar
--loadorder 300
--property oracle.hsgbu.ohmpi.ihe.hl7v2.home=[your HL7 v2 server folder root path]
hl7v2
Note:
If you used a colon in the property, you need to escape it with an "\\", for example:<property_ABC>=C\:\\hl7v2Client
rather than
<property_ABC>=C:\hl7v2Client
Restart your GlassFish server.
Log in to the GlassFish Admin Console.
Click the Lifecycle Modules node in the left panel, then click the New button in the right panel under Lifecyle Modules.
The New Lifecyle Module dialog appears. We are going to assume that we are creating the Audit Repository LifeCycle Module to complete this procedure.
In the Name field, type the name of for your module (for example, hl7v2
).
It is a good idea to choose a name that represents the module. "Arr" stands for Audit Record Repository.
In the Class Name field, type oracle.hsgbu.ohmpi.ihe.hl7v2.management.HL7ServiceGFManager
.
Note:
The class name can only contain alphanumeric, underscore, dash, and dot characters.In the Classpath field, type the path to the <your HL7v2 Server root path>
/lib/ihe-mpi-hl7v2-management.jar
file.
Note:
You can leave this field blank if the class is already in the server's class path.(Optionally) In the Load Order field, set the order in which you want the lifecycle modules to load when the application server starts up.
Note:
Modules with smaller integers load earlier.(Optionally) In the Description field, describe the lifecycle module.
Select the Status check box.
To prevent an instance startup if a module load fails, select the On Load Failure check box.
Click OK to save your selections.
A newly created lifecycle module with the name you gave it appears under Lifecycle Modules in the left panel (for example, hl7v2
).
Click the newly created lifecycle module to edit it. Open it in the Edit Lifecycle Module dialog. Edit it and use the "Add Property" button to add one property:
It appears in the Edit Lifecycle Module dialog, with the fields populated.
Under Additional Properties, click the Add Property button, and do the following to configure your hl7v2 home directory:
For Name type oracle.hsgbu.ohmpi.ihe.hl7v2.home
.
For Value type <your hl7v2 server folder root path>
.
Restart GlassFish to load the lifecycle module.
After you have installed and configured lifecycles on GlassFish you can administer them from the command line.
Start your application server (if it is not already running).
Run the subcommand list-lifecycle-modules.
Note:
Run the command in remote mode.Start your application server (if it is not already running).
Run the subcommand list-lifecycle-modules to obtain a list of your current lifecycles.
Note:
Run the command in remote mode.Run the subcommand delete-lifecycle-module to delete a lifecycle module.
Before running OHMPI with IHE Profiles you must configure application server resources.
The IHE Profiles Application maintains connections to several databases to comply with IHE requirements for monitoring, audit logging, and master data management.
The following procedure outlines the steps to create a connection pool. The configuration information for each connection pool you need to create is listed after the procedure.
Log in to the GlassFish Admin Console.
You can access the console from the Services window in NetBeans IDE.
In the left portion of the Admin Console, expand Resources, expand JDBC, and then select Connection Pools.
On the Create Connection Pool page, click New.
In the Name field, enter a name for the connection pool. See the informal table at the end of this section for information about the connection pools.
Note:
To complete steps 4 and 5 see the informal table at the end of this section for the four connection pools to be configured.In the Resource Type field, select the Java class for the type of transactions being processed.
In the Database Vendor field, select MySQL.
Click Next.
In the DataSource Classname field, accept the default class.
Modify the Pool Settings, Connection Validation, and Transaction properties according to your business practices.
In the additional properties section, enter the values for the database. Be sure to enter the following properties at a minimum (you might need to create some of these properties).
URL: The URL that points to the database. The syntax of the URL is jdbc:mysql://
<server>
:
<port>
/
<DatabaseName>
.
server
: The name of the server where the database is located.
port
: The port number of the database. For MySQL, the default port is 3306.
DatabaseName
: The name of the database schema.
User: The login ID for database user.
Password: The password for the above user.
DatabaseName: The name of the database schema.
Note:
These properties are mandatory. Also note that the database name in the URL must match the name given to the DatabaseName property.Create the connection pools listed below. The database vendor for all pools is MySQL. The port number and server name depend on your MySQL environment, and the URL you enter depends on these values. The user and password properties are the ones you defined for each database schema in "Creating the IHE Profiles Application Databases and Tables".
Note:
You do not have to use the connection pool names given here. These are the default names given by the installer.Connection Pool Name | Resource Type | Database Name | Purpose |
---|---|---|---|
cpPatientXA | The type corresponding to the type of transaction processed by the master person index. The default is javax.sql.XADataSource. | mpi | Connecting to the Master Person Index database. |
cpPatientSequenceXA | The type corresponding to the type of transactions that are distributed, either within the application or across applications The default is javax.sql.XADataSource. | mpi | Connecting to the Master Person Index sequence table. |
cpPIXDomainLU | javax.sql.DataSource | mpi | Connecting to the Domain Lookup table. |
cpPIMPendingLinksXA | javax.sql.XADataSource | mpi | Connecting to the PAM/PIM Pending Links table. |
The IHE Profiles Application maintains connections to several databases to comply with IHE requirements for monitoring, audit logging, and master data management.
The following procedure outlines the steps to create a connection pool. The configuration information for each connection pool you need to create is listed after the procedure.
Log in to the GlassFish Admin Console.
You can access the console from the Services window in NetBeans IDE.
In the left portion of the Admin Console, expand Resources, expand JDBC, and then select Connection Pools.
On the Create Connection Pool page, click New.
In the Name field, enter a name for the connection pool.
Note:
To complete steps 4 and 5 see the informal table at the end of this section for the four connection pools to be configured.In the Resource Type field, select the Java class for the type of transactions being processed.
In the Database Vendor field, select Oracle.
Click Next.
In the DataSource Classname field, accept the default class.
Modify the Pool Settings, Connection Validation, and Transaction properties according to your business practices.
In the additional properties section, enter the values for the database. Be sure to enter the following properties at a minimum (you might need to create some of these properties).
URL: jdbc:oracle:thin:@
<server>
:
<port>
/
<SID>
server
: The name of the server where the database is located.
port
: The port number of the database. For Oracle, the default port is 1521.
SID
: The name of the database schema.
User: The login ID for database user.
Password: The password for the above user.
DatabaseName: The name of the database schema.
Note:
These properties are mandatory. Also note that the database name in the URL must match the name given to the DatabaseName property.Create the connection pools listed below. The database vendor for all pools is Oracle. The port number and server name depend on your Oracle environment, and the URL you enter depends on these values. The user and password properties are the ones you defined for each database schema in "Creating the IHE Profiles Application Databases and Tables".
Note:
You do not have to use the connection pool names given here. These are the default names given by the installer.Connection Pool Name | Resource Type | Database Name | Purpose |
---|---|---|---|
cpPatientXA | The type corresponding to the type of transaction processed by the master person index. The default is javax.sql.XADataSource. | mpi | Connecting to the Master Person Index database. |
cpPatientSequenceXA | The same as above. | mpi | Connecting to the Master Person Index sequence table. |
cpPIXDomainLU | javax.sql.DataSource | mpi | Connecting to the Domain Lookup table. |
cpPIMPendingLinksXA | javax.sql.XADataSource | mpi | Connecting to the PAM/PIM Pending Links table. |
The following procedure outlines the steps to create a JDBC resource. The configuration information for each resource you need to create is located after the procedure.
In the left portion of the Administration Console, expand Resources, expand JDBC, and then select JDBC Resources.
On the Create JDBC Resource page, click New.
In the JNDI Name field, enter a unique name for the JDBC resource.
In the Pool Name field, select the name of a JDBC connection pool.
In the Status field select the Enabled check box.
Click OK.
Create the JDBC Resources listed below, which correspond to the connection pools you created earlier. Note that several of the JNDI names are case-sensitive.
JNDI Name | Pool Name |
---|---|
jdbc/PatientDataSource | cpPatientXA |
jdbc/PatientSequenceDataSource | cpPatientSequenceXA |
jdbc/PIXDomainLUDataSource | cpPIXDomainLU |
jdbc/PIMPendingLinksDataSource | cpPIMPendingLinksXA |
The IHE Profiles Application uses JMS topics to make outbound patient notification updates available to the domains that subscribe to those updates. The Oracle Healthcare Master Person Index generates outbound messages for patient updates in XML format to the PatientTopic destination. The PIX Update Manager that handles update notifications make the information available to either HL7 v2 or HL7 v3 destinations according to the IHE framework.
You create the JMS artifacts manually as described below.
In the left portion of the Admin Console, expand Resources, expand JMS Resources, and then select Connection Factories.
On the New JMS Connection Factory page, click New.
Enter the following information:
JNDI Name - jms/PatientOutBoundSender (this name is case-sensitive)
Resource Type - javax.jms.TopicConnectionFactory
Create the following additional properties and enter the property values:
UserName - A JMS user name. The default user name is admin.
Password - A password for the above user name. The default password is admin.
Click OK.
In the left portion of the Administration Console, select Destination Resources under JMS Resources.
On the New JMS Destination Resource page, click New.
Use this page to create the following topics:
JNDI Name | Resource Type | Physical Destination Name | Purpose |
---|---|---|---|
jms/PatientTopic | javax.jms.Topic | PatientTopic | Updates to the Master Person Index patient records are written to this topic. |
jms/PixUpdateNotificationTopic | javax.jms.Topic | PixUpdateNotificationTopic | HL7 v2 and v3 updates to patient records are processed through a Java EE Message Driven Bean and written to this topic. |
You create user accounts for MIDM access using the GlassFish Admin Console. There are two predefined user groups for the MIDM, and you can define additional user groups each with different permissions. For more information about configuring user groups (roles) for MIDM, "Defining Master Index Data Manager Security" in Oracle Healthcare Master Person Index Data Manager's Guide (Part Number E18469-01).
Log on to the GlassFish Administration Console.
In the left navigation panel, expand Configuration, expand Security, and then expand Realms.
Select File.
On the Edit Realm page, select Manage Users.
The File Users page appears.
On the File Users page, select New.
In the User ID field, enter a name for the user.
In the Group List field, for MIDM users, type MasterIndex.Admin
and any of the predefined user groups or user groups that you defined (for example, Administrator
). Separate multiple roles with a comma (no space).
Enter a password for the user in the New Password field.
In the Confirm New Password field, enter the password again.
Click OK.
Note:
This configuration step is optional.In order to support secure IHE Profiles applications on the HL7 v3 (web service) side, the application server needs to have correct keystore and truststore setup.
Suppose XXX
.key.pem
and XXX
.cert.pem
are your private key and the corresponding public certificate in X509 format, respectively. Also suppose ca.cert.pem
is the public certificate of the CA that signed your certificate, and cacerts.jks
is the existing GlassFish truststore under <Glassfish>
/domains/
<domain_name>
/config
. To import keys and certificates into GlassFish's keystore and truststore, use the following steps:
Create a temporary working directory that contains the above four files.
Transform X509 certificates and keys to pkcs#12 format using openssl tool:
openssl pkcs12 -export -inkey
XXX
.key.pem -in
XXX
.cert.pem -out
XXX
.pkcs12 -name s1as
Enter Export Password: changeit
.
Confirm the Export Password.
Import the pkcs#12 certificate into a brand new JKS keystore using keytool:
keytool -importkeystore -srckeystore
XXX
.pkcs12 -srcstoretype pkcs12 -srcstorepass changeit -srcalias s1as -destkeystore keystore.jks -deststoretype jks -deststorepass changeit
Import the public certificate of the CA into the existing truststore using keytool:
keytool -importcert -file ca.cert.pem -keystore cacerts.jks -storepass changeit
(Optional) Back up your existing GlassFish application server's keystore (keystore.jks
) and truststore (cacerts.jks
) under <Glassfish>
/domains/
<domain_name>
/config
.
Copy the new keystore (keystore.jks
) and truststore (cacerts.jks
) generated in steps 3 and 4 above to <Glassfish>
/domains/
<domain_name>
/config
.
Start GlassFish if it is not started.
Log in to the Admin Console.
Select Application Server on the left side tree, then select JVM Settings, and then JVM Options on the right hand side, make sure the keyStore and trustStore properties are set correctly, for example:
-Djavax.net.ssl.keyStore=${com.sun.aas.instanceRoot}/config/keystore.jks
-Djavax.net.ssl.trustStore=${com.sun.aas.instanceRoot}/config/cacerts.jks
Select Configuration on the left hand side tree, then HTTP Service, HTTP Listeners, http-listener-2. On the right hand side, in the Edit HTTP Listener tab, make sure that Listener and Security are both enabled and the Listener Port is properly configured (for example, 8181).
In the SSL tab, make sure TLS is enabled and the Certificate NickName matches the alias you used in step 2 (for example, s1as).
If the Client Authentication check box is not checked, then only server authentication is required. To enable client authentication (or mutual authentication) for all applications deployed on the application server, check the Client Authentication checkbooks. Note that even if the client authentication is not enabled here, individual application deployed on the application server can still require client authentication on a per-endpoint basis. Refer to "Creating an IHE Profiles Application Project" on how to secure web service endpoints in an IHE application.
Note:
Even if the client authentication is not enabled here, an individual application deployed on the application server can still require client authentication on a per-endpoint basis. See "Creating an IHE Profiles Application Project" for information on how to secure web service endpoints in an IHE Profiles Application.If specific ciphersuites are required during SSL/TLS handshake, select the desired ciphersuites from the Available Common Ciphersuites list and click Add to place them in the Selected Common Ciphersuites list.
If any changes need to be made during steps 9 through 13, save the changes and restart the application server.