Oracle® Health Sciences Information Gateway Secure Health Email Installation and Configuration Guide Release 2.0.1 E37028-02 |
|
|
PDF · Mobi · ePub |
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."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.Copy the files under <install_dir>/addons/direct/config/files/database/oracle
to a machine with Oracle SQL*Plus installed.
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.
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
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
To prepare the OHIG Secure Health Email database tables for Oracle:
Copy the files under install_dir>/addons/direct/config/files/database/oracle
to a machine with Oracle SQL*Plus installed.
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.
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
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
Execute the following commands to install the Secure Health Email:
$ tar -zxvf ohig_direct_installer.tgz
$ cd ohig_direct_installer
$ 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".
This provides the settings for configuring OHIG Secure Health Email, the Apache Mail Server for SSL, and the Remote Manager:
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.> cd <install_dir>/addons/direct/config
> 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
.> stop
> 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".
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 parameterjames_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
> cd <james_install_dir>/apps/james/SAR-INF
Edit the config.xml
file.
Search for "pop3server" and uncomment:
<!--
<useTLS>true</useTLS>
--!>
Search for "smtpserver" and uncomment:
<!--
<useTLS>true</useTLS>
--!>
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 specifyjavax.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>
cd <james_install_dir>/apps/james/SAR-INF
Edit the config.xml
file.
Search for "remotemanager", and edit the following two lines:
<port>4555</port>
<account login="root" password="root"/>
To enable secure telnet, uncomment:
<!--
<useTLS>true</useTLS>
--!>
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
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.Start the Apache James Mail Server with the system property:
-Djava.util.logging.config.file=logging.properties
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:
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:
Stop the sendmail process.
# service sendmail stop Shutting down sm-client: [ OK ] Shutting down sendmail: [ OK ]
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
To stop the Apache James Mail Server run the command
# <james_install_dir>/bin/phoenix.sh stop
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.
See Appendix B, "Oracle Health Sciences Information Gateway Secure Health Email Configuration Tool" for configuration instructions.
> cd <james_install_dir>/bin/templates
Edit the files in the templates
directory (see Appendix D, "System Email Template Reference").
> cd <install_dir>/addons/direct/config/openssl_starter
Follow the instructions in the README.txt
file.
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.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');
Log into the OHMPI machine.
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
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:
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.
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. |
|
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. |
|
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 |
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:
Log into the OHIM Health Record Locator.
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
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>