Oracle® Health Sciences Information Gateway Secure Health Email Installation and Configuration Guide Release 1.2 E22884-01 |
|
|
PDF · Mobi · ePub |
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 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 H, "High-level Network Diagram."There are two sections with details about preparing the databases:
For advanced configuration information, follow the links provided in Appendix I, "Apache James Mail Server."
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 /home/hiauser/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 /home/hiauser/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
In the OHMPI Oracle Database, create an OHMPI source system for the Secure Health Email Server to create new patients.
Note:
Make sure to enable patient feed from OHMPI to RLS as described in section 1.4.3, “Configuring Assigning Authority Patient Feed - Application Server,” in Oracle Health Sciences Information Manager OHMPI Installation and Configuration Guide (Part Number E22762-01).Execute SQL (below) in the OHMPI database using OHMPI DB user account.
Note:
Record If the value in the “systemcode” column is different than “1.1.1”, record the value.INSERT INTO sbyn_systems (systemcode, description, status, id_length,format, input_mask, value_mask, create_date, create_userid) VALUES ('1.1.1', 'ORCL_DIRECT', 'A', 23, '[0-9]{23}', 'DDDDDDDDDDDDDDDDDDDDDDD', 'DDDDDDDDDDDDDDDDDDDDDDD', sysdate, 'MPI');
This provides the settings for configuring OHIG Secure Health Email, the Apache Mail Server for SSL, and the Remote Manager:
Note:
For advanced configuration information follow the links provided in Section I.3, "Apache James Mail Server".Using the OHIG Secure Health Email Configuration Tool, update the tables with initial data as listed below. See Appendix A, "The OHIG 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.
Example: ant direct-add-domain -Ddomain_name=secure.health-enterprise.org
Add trusted anchors which could include trusted Certificate Authorities.
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.
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/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 -Dendpoint=Dr.John.Doe@ health-enterprise.org
> cd /home/hiauser/config
Edit the config.properties
file.
Note:
Refer tohttp://download.oracle.com/javase/6/docs/api/java/util/Properties.html
for property file formatting rules. This link specifies formatting rules for config.properties
.OHIG Secure Health Email Settings
james_init.xdsRegistryEndpointUrl
XDS registry endpoint URL used to query for submission set documents and metadata.
james_init.xdsRepositoryEndpointUrl
XDS.b repository URL. In case you are testing against the HIG Adapter Repository service, your URL will look like the following URL:
http://
<OHIG_ADAPTER_HOST>:8080/CONNECTAdapter/DocumentRepository_Service
james_init.xdsRepositoryId
XDS repository UID.
james_init.xdsDocumentOidRoot
Object ID root to be used while generating new document UUIDs.
james_init.xdsSubmissionSetOidRoot
Object ID root to be used while generating new submission set UUIDs.
james_init.assigningAuthorityId
OID of XDS affinity domain assigning authority. Used as "root" of the patient ID in conjunction with the EUID, which is used as "extension". This should match with the Assigning Authority OID configured in the HIG Adapter and OHMPI.
james_init.mpiServiceUrl
OHMPI's web service endpoint URL.
james_init.mpiSystemCode
System code setup in OHMPI for use by the OHIG Secure Health Email for creating new patients. The value should be the one noted in the previous step ("Setting Up a New Source System in OHMPI for Secure Health Email Server"), followed to update the OHMPI database.
james_init.mpiDelayAfterPatientInsertSecs
Wait time in seconds before XDS processing to allow for OHMPI to send patient feed XDS registry.
james_init.domain
Hostname of OHIG Secure Health Email.
james_init.systemEmailAddress
OHIG Secure Health Email system email address used to send Message Disposition Notification messages, Notification of Document Availability messages, and error message notifications.
james_init.manualEmailAddress
Email address which receives error message notifications.
james_init.useIheNav
Flag determining whether or not to use standard IHE Notification of Document Availability messages.
james_init.arrHost
Policy Monitor hostname.
james_init.arrPort
Policy Monitor port number.
Apache James Mail Server Database Settings
james_db.driver (Example: oracle.jdbc.driver.OracleDriver)
Database driver class.
james_db.dburl (Example: jdbc:oracle:thin:@<ORACLE_HOSTNAME>:1521:orcl)
Database connection URL.
james_db.username (Example: jamesuser)
Database username.
james_db.password (Example: jamespass)
Database password.
OHIG Secure Health Email Database Settings
direct_db.driver (Example: oracle.jdbc.driver.OracleDriver)
Database driver class.
direct_db.dburl (Example: jdbc:oracle:thin:@<ORACLE_HOSTNAME>:1521:orcl)
Database connection URL.
direct_db.username (Example: directuser)
Database username.
direct_db.password (Example: directpass)
Database password.
> ant config-james
For advanced configuration properties, see Appendix E, "Advanced OHIG Secure Health Email Property Reference".
> cd /home/common/james/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 /home/common/james/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 /home/common/james/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 /home/common/james/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 prior to 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:
In order for the default SMTP email ports to open, the James Email Server needs to be started by root user.Use the UNIX aliases set for root
and hiauser
to start and stop James server service.
Stop the James service running with default configuration by running the alias command “stop”.
Start the James service to run with newly configured parameters, by running the alias command “start”.
Use the alias command “jameslog” to see a running tail-end view of the James console log.
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 A, "The OHIG Secure Health Email Configuration Tool" for configuration instructions.
Editing the System Email Templates
> cd /home/common/james/bin/templates
Edit the files in the templates
directory (see Appendix C, "System Email Template Reference").