Skip Headers

Oracle® Health Sciences Information Gateway Secure Health Email Installation and Configuration Guide Release 2.0.1 E37028-02 |
Home | Book List | Contents | Index | Contact Us

Previous | 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:

- Preparing the Databases

- Installing the Apache James Mail Server

- Configuring the Apache James Mail Server

- Managing the Apache James Mail Server

- Configuring Oracle Health Sciences Information Gateway Secure Health Email

- Additional Configuration

- Testing Secure Health Email

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:

- Configuring Apache James Mail Server for SSL

- Configuring Oracle Health Sciences Information Gateway Secure Health Email Properties

- Configuring 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:

- Starting the Apache James Mail Server

- Connecting to the Remote Manager

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

   Note:

   Make sure to enable patient feed from OHMPI to OHRL as described in Enabling Assigning Authority Patient Feed from Oracle Healthcare Master Person Index to Oracle Health Sciences Information Manager Health Record Locator.

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.

Note:

See also Table F-1, "Advanced Secure Health Email Properties".

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