Installation

Preface

Configuring and installing the self book project involves two servers.

1. The original OSCAR itself.  These instructions will work for OSCAR 12.1 and newer
   
2. The selfbook server.  This is the server that administers appointment setting, and is normally accessed directly by the client/patient

These servers can be on the same machine or separated. 

If you are installing on the same machine as an OSCAR 15 instance you can skip the details for installing Java and Tomcat and start with the War file installation section

Separate Selfbooking Server

Java 8 Installation

Technically any Java 7 or newer may do, however development is done on Oracle Java 8.

Details on Oracle Java PPA approach: http://www.webupd8.org/2012/09/install-oracle-java-8-in-ubuntu-via-ppa.html

Paste this lines on your root prompt and accept the Oracle License terms:

echo "deb http://ppa.launchpad.net/webupd8team/java/ubuntu xenial main" | tee /etc/apt/sources.list.d/webupd8team-java.list
echo "deb-src http://ppa.launchpad.net/webupd8team/java/ubuntu xenial main" | tee -a /etc/apt/sources.list.d/webupd8team-java.list
apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys EEA14886
apt-get update
apt-get install oracle-java8-installer

Test it if needed:

# java -version
java version "1.8.0_91"
Java(TM) SE Runtime Environment (build 1.8.0_91-b14)
Java HotSpot(TM) 64-Bit Server VM (build 25.91-b14, mixed mode)

 Tomcat 7 Installation 

sudo apt-get update
sudo apt-get install tomcat7

sudo service tomcat7 stop
Stopping Tomcat servlet engine tomcat7 [ OK ]

sudo nano /etc/default/tomcat7

JAVA_HOME=/usr/lib/jvm/java-8-oracle

sudo service tomcat7 start

/usr/share/tomcat7/bin/version.sh

Now change to a directory and then skip to the instructions that follow for setting up SSL work

cd /var/lib

SSL connections for Everyone

sudo $JAVA_HOME/bin/keytool -genkey -alias tomcat -validity 3650 -keyalg RSA -keystore /var/lib/tomcat7/.keystore -keypass liyi -storepass liyi

sudo nano tomcat7/conf/server.xml

Now adjust the data so it looks something like the below (ports 8090 and 8091 used below as they don't conflict with default Tomcat6 settings) changing the location of the keystore File and the keystore password to match the actual ones you used. 

   <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/lib/tomcat7/.keystore"
               keystorePass="liyi"   />

b) Install Oscar's Server Certificate

Copy over the base64 certificate from the -BEGIN CERTIFICATE- to the -END CERTIFICATE- you are using on the Oscar server.  if you can't access the certificate easily (you can view the certificate in FireFox) the following script may help

#!/bin/sh
#
# usage: retrieve-cert.sh remote.host.name [port]
#
REMHOST=$1
REMPORT=${2:-443}
echo |\
openssl s_client -connect ${REMHOST}:${REMPORT} 2>&1 |sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p'

sample usage to extract the certificate for an Oscar server on 10.69.241.1 accessed on ssh on port 8443 would be

retrieve-cert.sh 10.69.241.1:8443 > oscar_certificate.file

Now add the certificate you are using for the OSCAR server to the myoscar's Java 7 keystore 

$JAVA_HOME/bin/keytool -import -alias oscar -file oscar_certificate.file -keystore /var/lib/tomcat7/.keystore

You will be prompted for the passwords for the keystore, the certificate to be imported will be displayed, and then you will be asked if you Trust it

Trust this certificate? [no]:  Yes
Certificate was added to keystore

Now reciprocate for the self book server's certificate on the OSCAR server.

Installation Combined with OSCAR *OR* Separate Server Installation

The following steps need to occur if you are installing the selfbook server on the same machine as OSCAR or if you have followed the above instructions and are installing on a separate server.

War File Installation

wget https://sourceforge.net/projects/oscarmcmaster/files/selfbook.war
sudo cp selfbook.war /var/lib/tomcat7/webapps/selfbook.war

mvn package -Dmaven.test.skip=true
sudo mv target/*-SNAPSHOT.war /var/lib/tomcat7/webapps/selfbook.war

Config.xml Settings

Edit /var/lib/tomcat7/webapps/selfbook/WEB-INF/classes/config.xml

If you are using self signed SSL certificates as installed by DEB or listed above you will probably need to enable that

<!-- set to true to allow self signed certificates / -->
<allow_all_ssl_certificates>true</allow_all_ssl_certificates>

This URL is used to provide links sent by email for the confirming and canceling functions.  Thus you must provide an address that can be reached from the internet and not localhost.  Ensure that you end the URL with /

<selfBookEndPointExternalURLPrefix>https://localhost:8443/selfbook/</selfBookEndPointExternalURLPrefix>>

Selfbook needs to communicate with the oscar server to determine available appointments and to book them.  For a selfbook installation on the same server as OSCAR set the URL as below, otherwise replace localhost with the LAN or internet accessible address.  Ensure that you end the URL with /

If that doesn't work configure with out the terminal /

<oscar_server_base_url>https://localhost:8443/oscar/ws/</oscar_server_base_url>

Then set the user for selfbook that you will configure in OSCAR as per the Configuration section.   In consistency with the Configuration section I am using selfbook as the user, but you can use any receptionist role restricted OSCAR user here.

<oscar_server_user>selfbook</oscar_server_user>

Provide the password for this user.  As no one will be typing it anywhere else, make the effort to make it strong (random with at least one number, one uppercase letter, one lowercase letter and one special symbol) and long (over 16 characters).

<oscar_server_password>87:c(@69T@NULz[`Ep/g;Dm</oscar_server_password>

Optional NO confirmation Emails:

The default settings will not send an email to allow for appointment confirmation and cancellation, but will display a message on the webpage that implies that one is sent.  If you choose not to send the email then you should blank the string values found in the /var/lib/tomcat7/webapps/selfbook/WEB-INF/classes/string_tables/string_en.properties for the following keys

ConfirmationEmailSentTo=
IfNoConfirmation=

OPTIONAL Confirmation Emails:

Resultant plain text emails will be sent such as

If you want to send these emails for for appointment confirmation and cancellation then adjust the password and salt which allows for an encrypted link to be sent to the patient.  The link is encrypted so that selfbook can perform the required function on the correct appointment, without providing any information about the appointment, or allowing someone to manually cancel or confirm appointments.  The salt needs to be written in hexadecimal (ie numbers 1-F where F represents 16 in hex).  It has to be random, be at least 8 bytes in length and has to have an even number of characters.  Note that if the key length is incorrect there will be an error before the appointments are displayed in the app (nothing will display for the user).  If that happens you might need to install Unlimited Strength security policies into your java.

<encryption_password>your_password</encryption_password>
<encryption_salt>1234567890ABCDEF</encryption_salt>

Then set your email and SMTP settings

        <sendmail>
                 <!-- this is the name for the "sender" for the email -->
                 <senderName>OSCAR Selfbook</senderName>
                 <senderEmail>no_reply@haileyburyfht.org</senderEmail>
                 <bccEmail>no_reply@null.org</bccEmail>
                 <receptionEmail>reception@selfbook.org</receptionEmail>
        </sendmail>    
             <smtp>
            <host>smtp.gmail.com</host>
            <!-- Standard port 25, 465 or 587 -->
            <ssl_port>465</ssl_port> 
            <user>yourgmailaccount@gmail.com</user>
            <password>pxekdr5dfdbwjb6qjgT</password>
          <!-- Debug setting to send to this email instead -->
            <recipient_override></recipient_override>
          <!-- Debug setting when true to print the message to log instead -->
            <print_instead_of_send>false</print_instead_of_send>
            <smtpTimeout>20000</smtpTimeout>
            <connection_security>ssl</connection_security>
            <trustAllHosts>false</trustAllHosts>>

Booking Configuration

The actual booking setup is done using the booking.xml file (or demobooking.xml) which is in /var/lib/tomcat7/webaps/selfbook/WEB-INF/classes/demo

Note: Make a backup of the file before you change it!

Most of the information in the file can be changed and will take effect immediately. There is no need to restart tomcat.

In the algorithm section, if the answerType = "listprov", you must supply the valid provider number(s) in the validation field.  The list should be prefixed and suffixed with a space. (eg. validation=" 1000 1001 1002 "

In the allowedProvider section, you must have valid providers. You can make the alias and providerNo the same.  If you specify invalid providers, the page will not appear.  The alias is used if you need different options for the same provider. (eg. Annual Exam - 60 min or Follow-up - 10 min) 

External Settings

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_selfbook_portal_config=override.xml" where override.xml is an xml config file which trumps the default one. 

There are several ways of adding in the system parameters, as a series of files and locations are checked for this type of configuration when tomcat starts up.  You can look that up if you like.

One way of doing this is to put this information into /etc/default/tomcat7

the JAVA_OPTS line that is already in the file

JAVA_OPTS="${JAVA_OPTS} -Doscar_selfbook_portal_config=/var/lib/tomcat7/webapps/selfbook_override.xml"

Obviously you will also specify in the selfbook.override.xml an alternate location for the booking configuration XML file