Skip Headers
Oracle® Healthcare Master Person Index Working With IHE Profiles
Release 1.1

Part Number E18591-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

4 Configuring an Application Server

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

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

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:

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 the HL7 v2 Lifecycle Module From the Command Line

To install IHE HL7 v2 lifecycle module to your target application server, perform the following:

  1. Unzip hl7v2.zip to a directory of your choice (for example, your OHMPI installation directory. The unzipped hl7v2 directory is your HL7v2 server home).

  2. Start your GlassFish server (if it is not already running).

  3. Navigate to your GlassFish installation's bin folder.

  4. 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

  5. Restart your GlassFish server.

To Configure the HL7 v2 Lifecycle Module From the GlassFish Admin Console

  1. Log in to the GlassFish Admin Console.

  2. 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.

  3. 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.

  4. 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.
  5. 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.
  6. (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.
  7. (Optionally) In the Description field, describe the lifecycle module.

  8. Select the Status check box.

  9. To prevent an instance startup if a module load fails, select the On Load Failure check box.

  10. 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).

  11. 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.

  12. 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>.

  13. Restart GlassFish to load the lifecycle module.

Administering Lifecycles From the Command Line

After you have installed and configured lifecycles on GlassFish you can administer them from the command line.

To List Lifecycles From the Command Line

  1. Start your application server (if it is not already running).

  2. Run the subcommand list-lifecycle-modules.

    Note:

    Run the command in remote mode.

    Example 4-1 Running the list-lifecycle-modules Subcommand

    asadmin> list-lifecycle-modules
    hl7v2
    Command list-lifecycle-modules executed successfully
    

To Delete a Lifecycle Module From the Command Line

  1. Start your application server (if it is not already running).

  2. Run the subcommand list-lifecycle-modules to obtain a list of your current lifecycles.

    Note:

    Run the command in remote mode.
  3. Run the subcommand delete-lifecycle-module to delete a lifecycle module.

    Example 4-2 Running the delete-lifecycle-module Subcommand

    asadmin> delete-lifecycle-module obsolete_hl7v2
    Command delete-lifecycle-module executed successfully
    

Configuring Application Server Resources

Before running OHMPI with IHE Profiles you must configure application server resources.

Creating the JDBC Connection Pools (MySQL)

The IHE Profiles Application maintains connections to several databases to comply with IHE requirements for monitoring, audit logging, and master data management.

To Create the JDBC Connection Pools (MySQL)

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.

  1. Log in to the GlassFish Admin Console.

    You can access the console from the Services window in NetBeans IDE.

  2. In the left portion of the Admin Console, expand Resources, expand JDBC, and then select Connection Pools.

  3. On the Create Connection Pool page, click New.

  4. 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.
  5. In the Resource Type field, select the Java class for the type of transactions being processed.

  6. In the Database Vendor field, select MySQL.

  7. Click Next.

  8. In the DataSource Classname field, accept the default class.

  9. Modify the Pool Settings, Connection Validation, and Transaction properties according to your business practices.

  10. 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.

Creating the JDBC Connections Pools (Oracle)

The IHE Profiles Application maintains connections to several databases to comply with IHE requirements for monitoring, audit logging, and master data management.

To Create the JDBC Connection Pools (Oracle)

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.

  1. Log in to the GlassFish Admin Console.

    You can access the console from the Services window in NetBeans IDE.

  2. In the left portion of the Admin Console, expand Resources, expand JDBC, and then select Connection Pools.

  3. On the Create Connection Pool page, click New.

  4. 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.
  5. In the Resource Type field, select the Java class for the type of transactions being processed.

  6. In the Database Vendor field, select Oracle.

  7. Click Next.

  8. In the DataSource Classname field, accept the default class.

  9. Modify the Pool Settings, Connection Validation, and Transaction properties according to your business practices.

  10. 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.

Creating the JDBC Resources for MySQL and Oracle

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.

To Create the JDBC Resources for MySQL and Oracle

  1. In the left portion of the Administration Console, expand Resources, expand JDBC, and then select JDBC Resources.

  2. On the Create JDBC Resource page, click New.

  3. In the JNDI Name field, enter a unique name for the JDBC resource.

  4. In the Pool Name field, select the name of a JDBC connection pool.

  5. In the Status field select the Enabled check box.

  6. 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

Creating JMS Destination Resources and Connection Factory

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.

To Create the JMS Destination Resources and Connection Factory

  1. In the left portion of the Admin Console, expand Resources, expand JMS Resources, and then select Connection Factories.

  2. On the New JMS Connection Factory page, click New.

  3. Enter the following information:

    • JNDI Name - jms/PatientOutBoundSender (this name is case-sensitive)

    • Resource Type - javax.jms.TopicConnectionFactory

  4. 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.

  5. Click OK.

  6. In the left portion of the Administration Console, select Destination Resources under JMS Resources.

  7. On the New JMS Destination Resource page, click New.

  8. 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.

Creating User Accounts for MIDM Access

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).

To Create User Accounts for MIDM Access

  1. Log on to the GlassFish Administration Console.

  2. In the left navigation panel, expand Configuration, expand Security, and then expand Realms.

  3. Select File.

  4. On the Edit Realm page, select Manage Users.

    The File Users page appears.

  5. On the File Users page, select New.

  6. In the User ID field, enter a name for the user.

  7. 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).

  8. Enter a password for the user in the New Password field.

  9. In the Confirm New Password field, enter the password again.

  10. Click OK.

Configuring Secure Web Services on GlassFish Enterprise Server v2.1.1

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:

  1. Create a temporary working directory that contains the above four files.

  2. 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.

  3. 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

  4. Import the public certificate of the CA into the existing truststore using keytool:

    keytool -importcert -file ca.cert.pem -keystore cacerts.jks -storepass changeit

  5. (Optional) Back up your existing GlassFish application server's keystore (keystore.jks) and truststore (cacerts.jks) under <Glassfish>/domains/<domain_name>/config.

  6. Copy the new keystore (keystore.jks) and truststore (cacerts.jks) generated in steps 3 and 4 above to <Glassfish>/domains/<domain_name>/config.

  7. Start GlassFish if it is not started.

  8. Log in to the Admin Console.

  9. 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

  10. 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).

  11. In the SSL tab, make sure TLS is enabled and the Certificate NickName matches the alias you used in step 2 (for example, s1as).

  12. 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.
  13. 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.

  14. If any changes need to be made during steps 9 through 13, save the changes and restart the application server.