Skip to content

Latest commit

 

History

History
259 lines (216 loc) · 21 KB

README.md

File metadata and controls

259 lines (216 loc) · 21 KB
Raw

The Inflection Navigator

A patient receives a serious diagnosis from his or her physician. The physician instructs the patient to setup 3 tests, see 2 specialists and read material on the condition -- all within 2 weeks.

This 'Inflection Point' in the patient's health requires a lot of effort and coordination. But, what if the patient's clinic designated a 'Navigator' to guide the patient through these activities. The Navigator follows a protocol tailored to the patient's diagnosis and ensures the protocol is completed in a timely and efficient manner. Each patient diagnosis requires the Navigator to manage a distinct set of activities within a scheduled time frame.

The Navigator needs a tool that assists them in:

  • Applying a consistent protocol of activities to each patient based on their diagnosis.
  • Managing each patient's progress in completing the protocol.
  • Tracking and detailing the outcome of each patient.

The Szollosi Healthcare Innovation Program and the Northwestern University Biomedical Informatics Center have built such a tool -- the Inflection Navigator.

For questions about the Inflection Navigator, please contact Michael Gurley, Warren Kibbe or Sean Whitaker at the Northwestern University Biomedical Informatics Center.

Technical Architecture

The Inflection Navigator is a hybrid application composed of the following components:

  1. A light-weight patient and provider registry written in Ruby on Rails.
  2. A protocol and patient-activity management Java web application based on the National Cancer Institute caBIG®'s Patient Study Calendar(PSC) -- an open-source Java web application.
  3. The ESUP CAS Server configured to authenticate against an unencrypted, file-based store of users. (Note! This configuration should only be used for testing purposes. For a production deployment, an institutional CAS server should be used or the ESUP CAS server should be reconfigured to authenticate against a secure store of users -- for example, an LDAP server. See http://esup-casgeneric.sourceforge.net/install.html for further details.)
  4. A proxy callback application to enable the patient and provider registry Ruby on Rails application to make CAS proxy calls to PSC. (Note! See the documentation for the RubyCAS-Client for an explanation of running a separate Rails application to enable CAS proxying: http://rubycas-client.rubyforge.org/)

Within this hybrid application, a seamless end-user experience is provided by a shared look and feel, inter-application communication via RESTful API calls and the implementation of single sign-on via the CAS protocol.

Source Code

All of the source code for the application is contained within its installation package. The official URLs for the application's components can be found at the following locations:

Installation Prerequisites

Installation Steps

These steps assume the prerequisites are installed on your target system.

Download The Software (Section 1)

  1. Download and unzip the installation package. It contains the following directories and files:
    1. A directory named 'psc' containg the files 'psc.war', 'psc_install.doc' and a directory named 'conf-samples'.
    2. A directory named 'inav' containg the file 'inav.war' and a directory named 'conf-samples'.
    3. A directory named 'inav_cas_callback' containing the file 'inav_cas_callback.war'.
    4. A directory named 'cas' containing the ESUP CAS server (the Yale ITS CAS server and CAS Generic Handler).

Create the Databases (Section 2)

  1. Create the PSC database. Replace the name 'study_calendar' in the following steps if you prefer a different name.
    1. Login to PostgreSQL with a user appropriate to your environment.
      psql -U postgres -W
    2. CREATE DATABASE study_calendar;
    3. CREATE USER study_calendar WITH CREATEDB PASSWORD 'study_calendar';
      (Replace the password with a suitably secure password.)
    4. ALTER DATABASE study_calendar OWNER TO study_calendar;
  2. Create the INAV database. Replace the name 'inav' in the following steps if you prefer a different name.
    1. Login to PostgreSQL with a user appropriate to your environment.
      psql -U postgres -W
    2. CREATE DATABASE inav;
    3. CREATE USER inav WITH CREATEDB PASSWORD 'inav';
      (Replace the password with a suitably secure password.)
    4. ALTER DATABASE inav OWNER TO inav;

Install and Configure PSC (Section 3)

  1. Find the 'datasource.properties' file in the 'psc/conf-samples' directory in the installation package.
  2. Move the 'datasource.properties' file to '$CATALINA_HOME/conf/psc'. If the 'psc' directory does not exist, create it and grant read permission on it to the user which runs Tomcat on your system.
  3. In the 'datasource.properties' file, enter the proper JDBC connection values as follows:
    JDBC Connection ParameterValue
    datasource.urlUse the proper JDBC url for your database. With a database named “study_calendar” this value would be 'jdbc:postgresql:study_calendar'.
    datasource.usernameThe username to connect to the database from Section 2.
    datasource.passwordThe password to connect to the database from Section 2.
  4. In the 'datasource.properties' file, uncomment the line (delete the ‘#’ symbol) for PostgreSQL.
  5. Find the 'psc.war' file in the 'psc' directory in the installation package.
  6. Move the 'psc.war' file to '$CATALINA_HOME/webapps'.
  7. Restart Tomcat.
  8. Using a web browser, go to the PSC URL as determined by your Tomcat configuration. This will most likely be similar to: http://hostname.domain:portnumber/psc. On a development workstation, this will most likely be: http://localhost:8080/psc
  9. Follow the on-screen instructions to create your first user and site. For more instructions regarding configuring PSC, please see the Patient Study Calendar Admin Guide and the Patient Study Calendar End User Guide
    1. For the initial setup of PSC, make sure you select 'local' for the Authentication System. Later it will change to CAS.
    2. Make sure to remember the 'username' and 'password' of the first User you create for PSC.
    3. Make sure to remember the 'site name' and 'assigned identifier' of your first PSC site. Only create one site within PSC. The INAV application currently only supports interacting with one PSC site.

Install and Configure the CAS server (Section 4)

Optional. If you already have a CAS server in your institution, move on to Section 5.

  1. Find the 'cas' directory in the installation package.
  2. Copy the 'cas' directory to '$CATALINA_HOME/webapps'.
  3. Make a directory named 'inav' in '$CATALINA_HOME/conf'. Grant read permission on the directory to the user which runs Tomcat on your system.
  4. Find the 'inav-users.txt' file in the 'inav/conf-samples' directory in the installation package.
  5. Move the 'inav-users.txt' file to '$CATALINA_HOME/conf/inav'. Grant read permission on the file to the user which runs Tomcat on your system.
  6. This is an unencrypted, file-based store of users that the CAS server will look up for authentication. It is a comma-separated list of 'username' and 'password'. The initial copy of the file has the values 'admin,password'. Replace it with the username and password that you entered in Section 3.
  7. Any new users added to PSC will need to be added to this file.
  8. Find the 'genericHandler.xml' file in the '$CATALINA_HOME/webapps/cas/WEB-INF' directory.
  9. Replace the content in the 'filename' element in the 'genericHandler.xml' file with the full path to the 'inav-users.txt' file. For example, on an OSX system this might be '/opt/local/share/java/tomcat5/conf/inav/inav-users.txt'.
  10. Find the 'LoggerConf.xml' file in the '$CATALINA_HOME/webapps/cas/WEB-INF' directory.
  11. Replace the content of the value attribute in the 'param' element with the path to the log directory of your system's Tomcat server. For example, on an OSX system this might be '/opt/local/share/java/tomcat5/logs/esup-casgeneric.log'.
  12. Test the CAS server
    1. Go to http://hostname.domain:portnumber/cas. On a development workstation, this will most likely be: http://localhost:8080/cas.
    2. Log in with the credentials you entered into the 'inav-users.txt' file. A message should appear saying 'You have been logged in successfully.'.

Configure Tomcat to Use SSL (Section 5)

The Java CAS client used by PSC requires that the CAS server be served over SSL.

  1. See http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html to learn how to enable SSL directly on a Tomcat server. Note! If a self-signed SSL certificate is not sufficient to meet your security policies, please investigate obtaining a certificate from a well-known CA
  2. $JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA -file tomcat.crt
    Note! The common name for the certificate created in this step should be a valid hostname for your system.
  3. The Java client used by PSC needs to trust the certificate created in the preceding step.
    keytool -import -keystore $JAVA_HOME/lib/security/cacerts -file tomcat.crt
  4. Test the CAS server running under SSL.
    1. Go to https://hostname.domain:portnumber/cas. On a development workstation, this will most likely be: https://localhost:8443/cas.
    2. Log in with the credentials you entered into the 'inav-users.txt' file. A message should appear saying 'You have been logged in successfully.'.

Configure PSC to Use CAS (Section 6)

  1. Log into PSC with the first user you setup in section 3.
  2. Click the 'Configure authentication' menu item
  3. Select 'CAS' from the list.
  4. Enter in the Service URL field the URL to your institution's CAS server or the URL to the CAS server you installed in section 5. On a development workstation, this will most likely be: https://localhost:8443/cas. Note! The host name of the CAS server must match the common name of the certificate you created in section 5.
  5. Enter in the PSC base URL field the URL to your PSC instance. On a development workstation, this will most likely be: https://localhost:8443/psc/

Install and Configure the INAV CAS Callback Application (Section 7)

The Ruby on Rails patient and provider registry component of the INAV application needs to make proxy CAS calls to the PSC application in order to retrieve and update information on behalf of the authenticated user. A limitation in the Rails platform necessitate a separate application to handle CAS proxy callbacks.

  1. Find the file 'inav.yml' in the 'inav/conf-samples/' directory in the installation package.
  2. Move the 'inav.yml' file to '$CATALINA_HOME/conf/inav/'.
  3. In the 'inav.yml' file, set the the following properties:
    PropertyValue
    cas.cas_base_url:The URL to your institution's CAS server or the URL to the CAS server installed in section 5.
    cas.proxy_retrieval_url:This will most likely be similar to: http://hostname.domain:portnumber/inav_cas_callback/cas_proxy_callback/retrieve_pgt. On a development workstation, it will most likely be: https://localhost:8443/inav_cas_callback/cas_proxy_callback/retrieve_pgt.
    cas.proxy_callback_url:This will most likely be similar to: http://hostname.domain:portnumber/inav_cas_callback/cas_proxy_callback/receive_pgt. On a development workstation, it will most likely be: https://localhost:8443/inav_cas_callback/cas_proxy_callback/receive_pgt.
  4. Find the 'inav_cas_callback.war' file in the 'inav_cas_callback' directory in the installation package.
  5. Move the 'inav_cas_callback.war' file to '$CATALINA_HOME/webapps'.
  6. Restart Tomcat. The file 'inav_cas_callback.war' should have expanded into a directory named '$CATALINA_HOME/webapps/inav_cas_callback/'.
  7. Test the Callback application
    1. Go to the URL you entered for the value of the cas.proxy_retrieval_url property in inav.yml. You should get the following response: 'No pgtIou specified. Cannot retreive the pgtId.'.
    2. Go to the URL you entered for the value of the cas.proxy_callback_url property in inav.yml. You should get the following response: 'Okay, the server is up, but please specify a pgtIou and pgtId.'.

Install and Configure INAV (Section 8)

  1. Find the file 'inav.yml' that you moved into the '$CATALINA_HOME/conf/inav/' directory in section 7.
  2. In the 'inav.yml' file, set the the following properties:
    PropertyValue
    default.hostThe host name of the computer where your PostgreSQL database server resides.
    inav.databaseThe name of the INAV database that you created in section 2, step 2.2.
    inav.usernameThe username of the owner of the INAV database that you created in section 2, step 2.2.
    inav.passwordThe password of the owner of the INAV database that you created in section 2, step 2.2.
    psc.psc_canonical_uriThe url to the PSC server setup in section 3. Note! It is important to end this URL with a trailing slash -- '/'.
    psc.psc_service_uriThe url to the PSC server setup in section 3 with following path appended: '/auth/cas_security_check'.
    psc.psc_siteThe 'assigned identifier' of the PSC site you setup in section 3.
    psc.psc_rest_urlThe url to PSC server setup in section 3 with following path appended: '/api/v1/'.
    smtp.addressThe url of the SMTP sever to send emails from.
    smtp.portThe port of the SMTP sever to send emails from.
    smtp.domainThe domain of the SMTP sever to send emails from.
    exception_notifier.exception_recipientsThe list of emails addresses to send exception notifications.
    exception_notifier.sender_addressThe email address to send exception notifications from.
    exception_notifier.email_prefixThe email prefix used to send exception notifications.
  3. Find the 'inav.war' file in the 'inav' directory in the installation package.
  4. Move the 'inav.war' file to '$CATALINA_HOME/webapps'.
  5. Restart Tomcat. The file 'inav.war' should have expanded into a directory named '$CATALINA_HOME/webapps/inav/'.
  6. Create the INAV database schema:
    1. Open a command shell and move to the directory '$CATALINA_HOME/webapps/inav/WEB-INF/'.
    2. Ensure that you have a CATALINA_HOME environment variable set. If you do not, set it. For example, on an OSX system this might be export CATALINA_HOME=/opt/local/share/java/tomcat5/.
    3. Ensure that you have a GEM_HOME environment variable set. If you do not, set it. For example, on an OSX system this might be export GEM_HOME=/opt/local/share/java/tomcat5/webapps/inav/WEB-INF/gems.
    4. Run the following command:
      java -jar lib/jruby-complete-1.4.0.jar -S rake db:migrate RAILS_ENV=production.
      This should create the database schema in the INAV database.
  7. Load Medical Record Number Types: Within the INAV system, patients can be assigned medical record numbers. Each medical record number has a medical record number type. A medical record number type might correspond to a Hospital or a Physician Group. The system does not come with any medical record number types. To setup medical record number types appropriate to your environment, perform the following steps:
    1. Find the file 'inav.yml' that you moved into the '$CATALINA_HOME/conf/inav/' directory in section 7.
    2. In the 'inav.yml' file, edit the entries in the 'medical_record_number_types' property to names appropriate to your environment.
    3. Open a command shell and move to the directory '$CATALINA_HOME/webapps/inav/WEB-INF/'.
    4. Ensure that you have a CATALINA_HOME environment variable set. If you do not, set it. For example, on an OSX system this might be export CATALINA_HOME=/opt/local/share/java/tomcat5/.
    5. Ensure that you have a GEM_HOME environment variable set. If you do not, set it. For example, on an OSX system this might be export GEM_HOME=/opt/local/share/java/tomcat5/webapps/inav/WEB-INF/gems.
    6. Run the following command:
      java -jar lib/jruby-complete-1.4.0.jar -S rake setup:medical_record_types RAILS_ENV=production.
      This should load the medical record number types into the INAV database.
  8. Test the INAV application
    1. Go to https://hostname.domain:portnumber/inav. On a development workstation, this will most likely be: https://localhost:8443/inav.
    2. Log in with the credentials you entered into the 'inav-users.txt' file. You should land on the Registrations page.
    3. To test the CAS authentication between INAV and PSC, click the link labeled 'go to Patient Study Calendar'. You should land on the Dashboard page of PSC without being prompted to log in again.

Roadmap

  1. Create an Inflection navigator User Guide that covers:
    1. Setting up protocols.
    2. Adding patients.
    3. Adding providers.
    4. Assigning providers to patients.
    5. Registering patients on protocols.
    6. Managing patient schedules.
  2. Create an administration interface to manage medical record number types.
  3. Automate the invocation of migrations upon deployment of the INAV .war file.
  4. Automate the patching of the JRuby rack library.
  5. Support other database platforms.
  6. Support other Java application server platforms.

Credits

The Inflection Navigator was developed for the Szollosi Healthcare Innovation Program by the Northwestern University Biomedical Informatics Center.

Copyright

Copyright (c) 2009 Northwestern University. See LICENSE for details.