Skip Headers
Oracle® Health Sciences Information Gateway Secure Health Email Installation and Configuration Guide
Release 2.0.1

E37028-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

2 Installing and Configuring OHIG Secure Health Email

Oracle Health Sciences Information Gateway (OHIG) has implemented the National Health Information Network (NHIN) to provide a secure, scalable, standards-based method of sending authenticated and encrypted health information to known and trusted recipients over the internet. OHIG Secure Health Email interacts with Oracle Health Sciences Information Manager (HIM) services, such as Oracle Healthcare Master Person Index (OHMPI), Document Registry, Repository, Policy Engine, and Audit Record Repository (ARR).

This chapter leads you through the steps to install, set up, and configure the James Mail Enterprise Server (James) version 2.3.2 to use with OHIG and Oracle Health Sciences Information Manager (OHIM). OHIG Secure Health Email is built on top of the Apache James Mail Server.

This chapter includes the following sections:

Note:

For a high-level overview of the Secure Health Email network, see Appendix J, "High-level Network Diagram."

2.1 Preparing the Databases

2.1.1 Preparing the Apache James Mail Server Database

To prepare the Apache James Mail Server database tables for Oracle:

Note:

Because the Apache James Mail Server Database stores sensitive data, it should be set up with encryption turned on.
  1. Copy the files under <install_dir>/addons/direct/config/files/database/oracle to a machine with Oracle SQL*Plus installed.

  2. Update the script create-james-user-oracle.sql with TABLESPACE parameters matching your environment. Also assign a password for the James database user by assigning a value to variable JAMES_USER_PASS. Remember to clear the value after you execute the script.

  3. To create the Apache James Mail Server database user load the script create-james-user-oracle.sql into the database.

    Example:

    > sqlplus system@<SID>
    SQL> @create-james-user-oracle.sql
    
  4. To create the Apache James Mail Server database load the script create-james-tables-oracle.sql into the database.

    Example:

    > sqlplus <JAMESUSER>@<SID>
    SQL> @create-james-tables-oracle.sql
    

2.1.2 Preparing the Secure Health Email Database

To prepare the OHIG Secure Health Email database tables for Oracle:

  1. Copy the files under install_dir>/addons/direct/config/files/database/oracle to a machine with Oracle SQL*Plus installed.

  2. Update the script create-direct-user-oracle.sql with TABLESPACE parameters matching your environment. Also assign a password for the OHIG Secure Health Email database user, by assigning a value to the variable DIRECT_USER_PASS. Remember to clear the value after you execute the script.

  3. To create the OHIG Secure Health Email database user load the script create-direct-user-oracle.sql into the database.

    Example:

    > sqlplus system@<SID>
    SQL> @create-direct-user-oracle.sql
    
  4. To create the OHIG Secure Health Email database load the script create-direct-tables-oracle.sql into the database.

    Example:

    > sqlplus <DIRECTUSER>@<SID>
    SQL> @create-direct-tables-oracle.sql
    

2.2 Installing the Apache James Mail Server

Execute the following commands to install the Secure Health Email:

  1. $ tar -zxvf ohig_direct_installer.tgz

  2. $ cd ohig_direct_installer

  3. $ java -jar ohig_direct_installer.jar

    To follow the prompts, refer to Appendix A, "Running the Oracle Health Sciences Information Gateway Secure Health Email Installer".

2.3 Configuring the Apache James Mail Server

This provides the settings for configuring OHIG Secure Health Email, the Apache Mail Server for SSL, and the Remote Manager:

2.3.1 Configuring Oracle Health Sciences Information Gateway Secure Health Email Properties

From this release of OHIG, you are not required to manually edit the file. You will be prompted through the script. Execute the following code to configure the OHIG Secure Health Email Properties

Note:

Before configuring the OHIG secure health email properties, update the install_dir>/addons/direct/config/install.properties file with the James installation path.
  1. > cd <install_dir>/addons/direct/config

  2. > ant create-config-properties-file

    [input] Enter james_domain
            [input] Enter james_postmaster_email
    [input] Enter james_system_email
    [input] Enter james_manual_email
            [input] Enter james_remotemanager_username
            [input] Enter james_remotemanager_password
            [input] Enter james_db_host
            [input] Enter james_db_port
    [input] Enter james_db_sid
            [input] Enter james_db_username
            [input] Enter james_db_password
            [input] Enter direct_db_host
    [input] Enter direct_db_port
    [input] Enter direct_db_sid
            [input] Enter direct_db_username
            [input] Enter direct_db_password
            [input] Enter arr_host
            [input] Enter arr_port
            [input] Enter xds_registry_url
            [input] Enter xds_pnr_repository_url
            [input] Enter xds_docretrieve_repository_url
            [input] Enter xds_repository_id
            [input] Enter xds_document_oid_root
    [input] Enter xds_submission_set_oid_root
    [input] Enter assigning_authority_id
    [input] Enter mpi_service_url
            [input] Enter mpi_system_code
    [input] Enter assigning_authority_oid
    [input] Enter assigning_authority_name
    [input] Enter pix_service_url 
    [input] Enter pdq_service_url
    [input] Enter mpi_system_oid
    [input] Enter mpi_system_name
            [input] Enter property_file_name
    

    Note:

    The Apache James Mail Server must be stopped prior to running > ant config-james.
  3. > stop

  4. > ant config-james

    For advanced configuration properties, see Appendix F, "Advanced Oracle Health Sciences Information Gateway Secure Health Email Property Reference".

    To edit a password in a properties file:

    > ant update-config-properties-file-password

    To edit a property in a properties file:

    > ant update-config-properties-file-property

    For more information, refer to Appendix H, "Password Encoding".

2.3.2 Loading Initial Data into Secure Health Email Database

Using the OHIG Secure Health Email Configuration Tool, update the tables with initial data as listed below. See Appendix B, "Oracle Health Sciences Information Gateway Secure Health Email Configuration Tool" for instructions on tool usage.

Note:

A version of Open SSL is available in the VM, and, if needed, you may want to use it.
  • Add a domain corresponding to your Secure Health Email Server's host name.

    For example, ant direct-add-domain -Ddomain_name=secure.health-enterprise.org

  • Add trusted anchors which could include trusted Certificate Authorities.

    For example, ant direct-add-anchor -Ddomain_name=secure.health-enterprise.org -Dcert_file=certs/oracle-cacert.der

  • Add trusted public certificates associating public certificates with external trusted email addresses.

    For example, ant direct-add-public-cert -Ddomain_name=secure.health-enterprise.org -Demail_address=Patient1@live.com -Dcert_file=certs/patient1-cert.der

  • Add trusted private certificates associating public or private certificate pairs with system secure email addresses. Note The email address used in this step should be used to update config parameter james_init.systemEmailAddress in the next section.

    Note:

    The email address used in this step should be used to update config parameter james_init.systemEmailAddress in the next section, "Configuring Apache James Mail Server for SSL".

    Example: ant direct-add-private-cert -Ddomain_name=secure.health-enterprise.org -Demail_address= direct@secure.health-enterprise.org -Dcert_file=certs/direct-cert.der -Dkey_file=certs/private/direct-key.der

  • Add trusted private certificates associating public/private certificate pairs with internal secure email addresses.

    Example: ant direct-add-private-cert -Ddomain_name=secure.health-enterprise.org -Demail_address= Dr.John.Doe@secure.health-enterprise.org -Dcert_file=certs/DrJohnDoe-cert.der -Dkey_file=certs/private/DrJohnDoe-key.der

  • Add addresses mapping internal secure email addresses to internal corporate email addresses and to a domain.

    Example: ant direct-add-address -Ddomain_name= secure.health-enterprise.org -Ddisplay_name="Dr. John Doe" -Demail_address=Dr.John.Doe@secure.health-enterprise.org -type=XD -Dendpoint=Dr.John.Doe@ health-enterprise.org

2.3.3 Configuring Apache James Mail Server for SSL

  1. > cd <james_install_dir>/apps/james/SAR-INF

    Edit the config.xml file.

    1. Search for "pop3server" and uncomment:

      <!--

      <useTLS>true</useTLS>

      --!>

    2. Search for "smtpserver" and uncomment:

      <!--

      <useTLS>true</useTLS>

      --!>

    3. Search for "server-sockets" and ensure the correct values are supplied below after un-commenting the tag <factory name=”ssl”..> :

      <factory name="ssl" class="org.apache.avalon.cornerstone.blocks.sockets.TLSServerSocketFactory">

      <ssl-factory>

      <keystore>

      <file>keystore/keystore.jks</file>

      <password>changeit</password>

      <key-password>changeit</key-password>

      <type>JKS</type>

      <protocol>SSLv3</protocol>

      <algorithm>SunX509</algorithm>

      <authenticate-client>false</authenticate-client>

      </keystore>

      </ssl-factory>

      </factory>

Note:

If connecting to remote SMTP gateway or SMTP server also thru SSL, makes sure to specify javax.net.ssl.SSLSocketFactory to use as socket factory by ”ExtendedRemoteDelivery” mailet.

For example:

<mailet match="RecipientIsRemote" class="ExtendedRemoteDelivery">
    …
    …
<mail.smtp.socketFactory.class>javax.net.ssl.SSLSocketFactory</mail.smtp.socketFactory.class>
    …
    …
</mailet>

2.3.4 Configuring the Remote Manager

  1. cd <james_install_dir>/apps/james/SAR-INF

    Edit the config.xml file.

    1. Search for "remotemanager", and edit the following two lines:

      <port>4555</port>

      <account login="root" password="root"/>

    2. To enable secure telnet, uncomment:

      <!--

      <useTLS>true</useTLS>

      --!>

2.3.5 Configuring Logging

Configuring Apache James Mail Server Logging

> cd <james_install_dir>/apps/james/SAR-INF

Edit the "log-level" settings in the environment.xml file.

Configuring Application Code Logging

  1. Create a JDK logging.properties file in the <james_install_dir>/bin directory.

    Example of a logging.properties file:

    handlers= java.util.logging.ConsoleHandler, java.util.logging.FileHandler.level= INFOjava.util.logging.ConsoleHandler.level = INFOjava.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter#java.util.logging.FileHandler.level = ALLjava.util.logging.FileHandler.formatter = java.util.logging.SimpleFormatterjava.util.logging.FileHandler.pattern = logs/direct%g.logjava.util.logging.FileHandler.limit = 50000java.util.logging.FileHandler.count = 10
    

    Note:

    You must create the logs directory under <james_install_dir>/bin before starting the server.
  2. Start the Apache James Mail Server with the system property:

    -Djava.util.logging.config.file=logging.properties

2.4 Managing the Apache James Mail Server

This section provides steps to start the Apache James Mail Server, and to connect to the Remote Manager and then manage the Apache James Mail Server:

2.4.1 Starting the Apache James Mail Server

Note:

For the default SMTP email ports to open, the James Email Server should be started by the root user.

Before starting the Apache James Mail Server, turn off the sendmail process as follows:

  1. Stop the sendmail process.

    # service sendmail stop
    Shutting down sm-client:   [  OK  ]
    Shutting down sendmail:    [  OK  ]
    
  2. Turn off the sendmail service.

    # chkconfig --list sendmail
    sendmail        0:off   1:off   2:on    3:on    4:on    5:on    6:off
    # chkconfig sendmail off
    # chkconfig --list sendmail
    sendmail        0:off   1:off   2:off   3:off   4:off   5:off   6:off
    

To start the Apache James Mail Server, execute the following command:

# <james_install_dir>/bin/phoenix.sh start

2.4.2 Stopping the Apache James Mail Server

To stop the Apache James Mail Server run the command

# <james_install_dir>/bin/phoenix.sh stop

2.4.3 Connecting to the Remote Manager

This section provides details for connecting to the Remote Manager and then managing the Apache James Mail Server. It also provides an example of adding a user.

> telnet localhost <PORT> (Default: 4555)

JAMES Remote Administration Tool 2.3.2

Please enter your login and password

Login id:

<USERNAME> (Default: root)

Password:

<PASSWORD> (Default: root)

Welcome root. HELP for a list of commands

HELP

Currently implemented commands:

  • help

    Displays this help.

  • listusers

    Displays existing accounts.

  • countusers

    Displays the number of existing accounts.

  • adduser [username] [password]

    Adds a new user.

  • verify [username]

    Verifies if a specified user exists.

  • deluser [username]

    Deletes the existing user.

  • setpassword [username] [password]

    Sets a user's password.

  • setalias [user] [alias]

    Locally forwards all email for 'user' to 'alias'.

  • showalias [username]

    Shows a user's current email alias.

  • unsetalias [user]

    Unsets an alias for 'user'.

  • setforwarding [username] [emailaddress]

    Forwards a user's email to another email address.

  • showforwarding [username]

    Shows a user's current email forwarding.

  • unsetforwarding [username]

    Removes a forward.

  • user [repositoryname]

    Changes to another user repository.

  • shutdown [repositoryname]

    Kills the current JVM (convenient when James is run as a daemon).

  • quit [repositoryname]

    Closes the connection.

2.4.3.1 Example of Add User

adduser <USERNAME> <PASSWORD>

Create system user (james_init.systemEmailAddress) and manual processor or error (james_init.manualEmailAddress) email user accounts configured earlier.

For example:

adduser direct directpass

adduser error errorpass

2.5 Configuring Oracle Health Sciences Information Gateway Secure Health Email

See Appendix B, "Oracle Health Sciences Information Gateway Secure Health Email Configuration Tool" for configuration instructions.

2.6 Additional Configuration

2.6.1 Editing the System Email Templates

> cd <james_install_dir>/bin/templates

Edit the files in the templates directory (see Appendix D, "System Email Template Reference").

2.6.2 Creating Test Certificates

> cd <install_dir>/addons/direct/config/openssl_starter

Follow the instructions in the README.txt file.

2.6.3 Setting Up Components

2.6.3.1 Setting Up a New Source System in Oracle Healthcare Master Person Index for Secure Health Email Server

  1. In the OHMPI Oracle Database, create an OHMPI source system and the corresponding IHE domain for the Secure Health Email Server to create new patients.

  2. Execute SQL (below) in the OHMPI database using OHMPI DB user account.

    Note:

    The value for "systemcode" in the "sbyn_systems" table should match the value for "namespaceid" in the "ihe_domains" table. Record the value for "namespaceid" and "universalid". These two values correspond to "mpi_system_name" and "mpi_system_oid" (see the next section), respectively.
    INSERT INTO sbyn_systems (systemcode, description, status, id_length,format, input_mask, value_mask, create_date, create_userid) VALUES ('ORCL_DIRECT', 'ORCL_DIRECT', 'A', 23, '[0-9]{23}', 'DDDDDDDDDDDDDDDDDDDDDDD', 'DDDDDDDDDDDDDDDDDDDDDDD', sysdate, 'MPI');
    INSERT INTO ihe_domains (namespaceid, universalid, universalidtype, description) VALUES ('ORCL_DIRECT', '1.1.1', 'ISO', 'Source System for Oracle Direct');
    

2.6.3.2 Enabling Assigning Authority Patient Feed from Oracle Healthcare Master Person Index to Oracle Health Sciences Information Manager Health Record Locator

  1. Log into the OHMPI machine.

  2. Edit the file <config_ohmpi_dir>/ohmpi-ihe.properties. See Table 2-1, "List of Properties in the ohmpi-ihe.properties File" for a list of the ohmpi-ihe.properties properties.

    GlassFish example:

    <glassfish_install_dir>/domains/<domain_name>/config/ohmpi/ohmpi-ihe.properties

    WebLogic example:

    <weblogic_install_dir>/user_projects/domains/<domain_name>/config/ohmpi/ohmpi-ihe.properties

  3. Ensure that the "aa/oid" value that you enter here matches with the one that is configured in the Secure Health Email Server and the OHIG Gateway. To do this:

    1. If the Secure Health Email Server is not yet configured, look at the property "james_init.assigningAuthorityOid" in the <install_dir>/addons/direct/config/config.properties file as this is used during the initial configuration set up. However, if it is already configured, look at the property "james_init.assigningAuthorityOid" in <james_install_dir>/bin/config.properties file.

    2. Also look at the corresponding OHIG Gateway property which is "assigningAuthorityId" in <config_nhin_dir>/adapter.properties file.

    Table 2-1 List of Properties in the ohmpi-ihe.properties File

    Property Name Description Example

    enable_patient_feed

    "true" enables sending Assigning Authority patient feed to OHRL, "false" disables it. In order for Secure Health Email to work, feed must be enabled.

    true

    enable_euid_query

    ”true” to return Global or EUID domain patient ID references also known as Affinity Domain Patient ID with PIX and PDQ queries. This must be ”true” for OHIG Secure Health Mail Server to get Affinity Domain Patient IDs.

    true

    registry/endpoint

    The URL of OHRL or XDS.b Doc Registry Web service endpoint URL.

    http://<oracle_registry_host_ip>:8080/hrl/regsvc

    aa/oid

    The Assigning Authority OID that OHMPI uses while sending a patient feed to OHRL.

    1.3.6.1.4.1.21367.2010.1.2.300

    aa/namespace

    The Assigning Authority Name.

    OHMPI Assigning Auth

    pisv3/device/oid

    Patient Identity Source v3 (Sender) Device Universal ID.

    1.3.6.1.4.1.21367.13.10.380

    pisv3/device/namespace

    Patient Identity Source v3 (Sender) Device Namespace ID.

    PIX_X_REF_MGR_ORACLE

    pisv3/device/org/oid

    Patient Identity Source v3 (Sender) Device Organization Universal ID.

    1.3.6.1.4.1.21367.13.50.5380

    pisv3/device/org/namespace

    Patient Identity Source v3 (Sender) Device Organization Namespace ID.

    Oracle

    registry/device/oid

    Registry (Receiver) Device Universal ID

    0.0.0.0.0.0.0.0.0.0

    registry/device/namespace

    Registry (Receiver) Device Namespace ID

    Registry_Device

    registry/device/org/oid

    Registry (Receiver) Device Organization Universal ID

    0.0.0.0.0.0.0.0.0.1

    registry/device/org/namespace

    Registry (Receiver) Device Organization Namespace ID

    Registry_Device_Organization


2.6.3.3 Adding Unknown Document Type's Coding Scheme to Oracle Health Sciences Information Manager Health Record Locator

The server uses the following "unknown" properties when it is not able to infer the coding scheme and codes, for Healthcare Facility Type or Practice Setting classifications, from the XDM metadata and CDA and/or CCD documents.

-- IHE specified class Scheme value for Healthcare Facility classification is urn:uuid:f33fb8ac-18af-42cc-ae0e-ed0b0bdb91e1.

  • unknownFacilityCodingScheme

  • unknownFacilityCode

-- IHE specified class Scheme value for Practice Setting classification is urn:uuid:cccf5598-8b07-4b77-a05e-ae952c785ead.

  • unknownPracticeSettingCodingScheme

  • unknownPracticeSettingCode

By default, the server will use 1.3.6.1.4.1.21367.3100.1.2 as the coding scheme and Unspecified as the code.

To add these coding schemes and codes to the OHIM Health Record Locator, perform the following steps:

  1. Log into the OHIM Health Record Locator.

  2. Edit the file <config_hrl_dir>/codes.xml.

    GlassFish example:

    <glassfish_install_dir>/domains/<domain_name>/config/hrl/codes/codes.xml

    WebLogic example:

    <weblogic_install_dir>/user_projects/domains/<domain_name>/config/hrl/codes/codes.xml

  3. Add the configured unknown document type's coding schemes to the HRL codes.xml file.

    For example,

    <CodeType name="healthcareFacilityTypeCode" classScheme="urn:uuid:f33fb8ac-18af-42cc-ae0e-ed0b0bdb91e1">
     ...
        <Code code="Unspecified" codingScheme="1.3.6.1.4.1.21367.3100.1.2" display="Unspecified"/>
    </CodeType> 
    
    <CodeType name="practiceSettingCode" classScheme="urn:uuid:cccf5598-8b07-4b77-a05e-ae952c785ead">
    ...
        <Code code="Unspecified" codingScheme="1.3.6.1.4.1.21367.3100.1.2" display="Unspecified"/>
    </CodeType> 
    

2.7 Testing Secure Health Email

Inbound and Outbound Examples

> cd <install_dir>/addons/direct/config/examples

Follow the instructions in the README.txt file.