MyOscar2 Installation for Oscar 11 and 12

The following instructions will install Tomcat 7 to your linux box and allow for the MyOscar servers to run

First change to a directory where you will install Tomcat 7

Note: /var/local was used because this particular installation already had Tomcat 6 installed and MyOscar was being added to the same machine.   If you are installing on a new server, you can put Tomcat in its normal location.

Then get the latest Tomcat 7 binary from Apache.  The version number below may have been superseded by the time you are reading this, so you may want to browse http://tomcat.apache.org/download-70.cgi for the best mirror and the number of the latest version .

 For convenience (and so that these instructions remain current) assign a symbolic link to the named directory

Setup a SSL certificate as per security hardening.  Now activate those connectors in server.xml specification taking care that you don't conflict with another services that might be using those ports.

   <Connector port="8090" protocol="HTTP/1.1"
               connectionTimeout="20000"
               redirectPort="8091" />  
   <Connector port="8091" protocol="HTTP/1.1" 
               SSLEnabled="true"
               maxThreads="200" 
               scheme="https" 
               secure="true" 
               enableLookups="false" 
               disableUploadTimeout="true" 
               clientAuth="false"  
               sslProtocol="TLS" 
               keystoreFile="/var/local/tomcat7/.keystore"
               keystorePass="liyi"   />

$ wget http://sourceforge.net/projects/myoscar/files/myoscar2/myoscar_server-2012-11-21.war
$ wget http://sourceforge.net/projects/myoscar/files/myoscar2/myoscar_client-2012-12-19.war
$ wget http://sourceforge.net/projects/myoscar/files/myoscar2/oscar_patient_portal-2012-12-19.war
$ sudo cp myoscar_server-2012-11-21.war $CATALINA_BASE/myoscar_server.war
$ sudo cp myoscar_client-2012-12-19.war $CATALINA_BASE/myoscar_client.war
$ sudo cp oscar_patient_portal-2012-12-19.war $CATALINA_BASE/oscar_patient_portal.war

OPTIONAL  If in development environment it may be useful to run the tests to check the build, to do that you need to setup a dbuser user with the dbpasswordf password for MySQL prior to compiling .  At the MySQL prompt type

mysql>CREATE USER 'dbuser'@'localhost' IDENTIFIED BY 'dbpassword';
mysql>GRANT ALL ON *.* to 'dbuser'@'localhost' IDENTIFIED BY 'dbpassword';

Note that running the tests creates a myoscar_server database that will need to be dropped prior to initializing with a blank database or test data.  For security reasons in production use remember to DROP USER the dbuser user or change the password to one that is not published after you are done with building.

OPTIONAL  For debugging purposes it may be useful to setup the tomcat manager application by editing tomcat-users.xml

sudo vi /var/local/tomcat7/conf/tomcat-users.xml

and add the following to the <tomcat-users> section (provide your own username and password)

sudo vi $CATALINA_BASE/myoscar_server/WEB-INF/classes/config.xml

	<database>
		<user>dbuser</user>
		<password>dbpassword</password>
		<url_prefix>jdbc:mysql://127.0.0.1:3306/</url_prefix>
		<schema>myoscar_server2</schema>
		<driver>com.mysql.jdbc.Driver</driver>
	</database>
	<smtp>
		<host></host>
		<ssl_port></ssl_port>
		<user></user>
		<password></password>
	</smtp>

	<myoscar_server>
		<https_endpoint_url_base>https://localhost:8091/myoscar_server/ws</https_endpoint_url_base>

Initialize the Database

Start Tomcat 7

cd /var/local/tomcat7/bin
sudo ./startup.sh

After installation and loading Tomcat you should go to http://localhost:8090/myoscar_server/admin/install.jsp to initialize the database. 

You will be warned if a database already exists (you will have to drop the schema manually if you want to reload a blank database)

Encryption is optional.  Probably you should NOT encrypt the database if you followed the instructions to encrypt the entire Ubuntu disk as suggested in the Oscar installation instructions.  Click the button.

 Wait a while and you will be given a screen with the following message:

MyOscar Server Admin

Then test that the connection works on http://localhost:8090/myoscar_server/ws

 Finally test that the connection also works on what you supplied for  "https_endpoint_url_base" in the XML file https://localhost:8091/myoscar_server/ws  as its this connection that the MyOscar client uses.  (you will see the same screen if it works)

MyOscar Client Configuration

sudo vi $CATALINA_BASE/myoscar_client/WEB-INF/classes/config.xml

cd /var/local/tomcat7/bin
sudo ./shutdown.sh
sudo ./startup.sh

Test your login to the client http://127.0.0.1:8090/myoscar_client

sudo vi /var/local/tomcat7/bin/setenv.sh

JAVA_OPTS="${JAVA_OPTS} -Dmyoscar_client_config=client_override.xml"

Yes we have to configure that too. 

First build the code or download the war archive

Second deploy/copy the war file into a servlet container like any standard war.

Edit config.xml. The 2 most important settings would be the oscar web services settings and the myoscar server web services settings, they need to be correct for this to connect to them.
   There's also 3 parameters that need to be setup, the list of oscar provider numbers, appointmentTypes, and time codes. These parameters control which providers show up on the booking list, what appointment types they can pick from, and what time slots in the providers schedule is eligible for online booking.
   You will need to have setup Oscar with the schedule templates for the providers working schedule. This means you must also have created appointment types and time codes for the schedule, also make sure you setup the holiday days properly in oscar.

sudo vi $CATALINA_BASE/myoscar_client/WEB-INF/classes/config.xml

cd /var/local/tomcat7/bin
sudo ./shutdown.sh
sudo ./startup.sh

From the myoscar_client side, assuming your configuration is correct, it should register itself with the myoscar system with in a minute if you starting the server. Once that happens you should see it as an option under the persons preferences.

Optional bit

TIP: If you are going to be re-installing the war, rather than redoing this every time, copy this modified configuration outside the application itself and reference it when you start tomcat.  To do that pass a system parameter of "-Doscar_patient_portal_config=override.xml" where override.xml is an xml config file which trumps the default one.  One way of doing this is to put this information into the bin directory of Tomcat7 in setenv.sh which gets run when you start Tomcat7 with 

sudo vi /var/local/tomcat7/bin/setenv.sh

You can specify a number of options here but for this purpose we want to add a parameter to JAVA_OPTS

JAVA_OPTS="${JAVA_OPTS} -oscar_patient_portal_config=portal_override.xml"

Oscar Configuration for MyOscar2

MY_OSCAR=yes
MY_OSCAR_EXCHANGE_INTERVAL = 2
ModuleNames=Indivo
myOSCAR.url = http://localhost:8080/myoscar_client/

If your Oscar database is not configured with MyOscar tables then load them (replace ***** with the MySQL root password and oscar_mcmaster with the name of the 11x database)

$ mysql -uroot -p********* oscar_mcmaster < $HOME/src/oscar_source/oscar/database/mysql/updates/update-phr-docs.sql 

Restart tomcat 6

sudo /etc/init.d/tomcat6 restart

When you login as oscardoc, go to the top menu "pref", near the bottom of the screen will be "set myoscar login id".

Enter the provider username you created above and save it.

Go to the patients master file record and hit "edit". On the right hand column between "country of origin" and "sin" should by " Register for MyOSCAR" option link. 

The subsequent screen should prompt you for your myoscar password. Once you fill that in, it should pre-populate most of the patients information. Provide a username ending with @myoscar.org and password for the patient, check off the provider who should be allowed to access that chart, then submit.  A warning "The user and corresponding permissions have been added. All checked providers must authorize this demographic as "patient" from the OSCAR Personal Health Record message screen before the patient can communicate with them. " will follow.

If you now go back to the patient ui, you should be able to login with that username/password.
On the left menu of the patient ui, there should be "messages", click on that. Click on "send new message". The "to" list should have your provider as an option, put in a test subject and a test message and send it. On the patient ui, on the left menu should be a "sent" option, you should now notice the message you just sent is in that list.

If you now go back to the oscar ui as the provider, click on the "myoscar" option on the top menu of the appointment/schedule screen. It should default to the inbox and you should see your test message. You should be able to reply etc to the message as well and verify that in the patient ui the patient sees the response etc.

Security Considerations

Securing your MyOscar box is beyond the scope of this paper.  However as MyOscar is designed to be accessible over the internet, we should be conscious of the issues.

The MyOscar client / patient ui by the nature of it's purpose, is meant to have an open port on the internet for patients to use.

The MyOscar server by virtue of it's design purpose is also meant to have an open port on the internet as other "Oscars" are suppose to be able to communicate with it. If you are not giving anyone else access to your MyOscar server then there's no need to forward or open *that* port.  So in most cases, keep that one closed.

Oscar itself is an in between case.  You mostly will access it on your LAN and only certain parties at certain locations will need to access it remotely. As described in security hardening, if you want to access it outside the LAN (and that is convenient), then for the few machines that need to do so you can can build an SSH tunnel with key authentication.

As for whether all 3 of these services are on the same machine or not, it should not really matter, however we have run into intermittent ssl_error_internal_error_alert with Firefox (only) on servers running both Tomcat 6 and Tomcat 7 on the same JVM.

You should not be opening any machine to the internet in any case. In theory you should only be opening the ports you need, i.e. the Myoscar client's http port. This makes it no less secure than any other http port on the planet like ebay's or your banks, or anything else.

To be nit picky about internal security, you could put all 3 applications on 3 different physical servers, heck why not put the database on a 4th server too, and have different passwords on all 4 servers and put firewalls up between all of them. You need to decide your effort vs returns. There would have to be a serious error/flaw in one of the applications web pages before anything else is compromised let alone significantly compromised.