search

ahcis-rds / study_finder

StudyFinder is a flexible and configurable application to pull studies from clinicaltrials.gov and augment the data from alternate datasources such as a clinical trials management system.
MIT License
17 stars 4 forks source link

readme

StudyFinder Build Status

StudyFinder is a flexible and configurable application that pulls studies from clinicaltrials.gov and augments the data from alternate datasources such as a clinical trials management system. StudyFinder also has a basic theming component which allows for even further customizations.

Contact the StudyFinder team at studyfinder@umn.edu if you:

Upgrade notes for 2.1

The main page carousel/video feature was an accessibility and usability issue, and has been replaced with a three-wide panel of "featured studies". These can be configured in the admin panel, where the carousel configuration formerly was.

Development

The easiest way to get started with a development environment is to use docker-compose:

  1. Run USER=username docker-compose run web rake db:setup to initialize your database and search index.

    The username value will be used to create an initial admin user; you should set it to the username you will use with LDAP authentication.

    By default, this loads studies from clinicaltrials.gov based on searching for the location 'University of Minnesota'. To change this for initial setup, edit this line in /app/db/seeds.rb:

    system = {
    ...
    search_term: 'University of Minnesota',
    ...
}

    (Once the site is up, this is availble as a setting in the front-end admin interface.)

  2. Run docker-compose up -d to start a development server.
  3. Visit http://localhost:3000/ to view the application.

Deployment

Running Study Finder on a web server requires:

  synonyms_path: '/usr/share/elasticsearch/config/analysis/synonyms.txt'.to_s
host: 'ldap.umn.edu'
port: 636
base: 'o=University of Minnesota,c=US'
encryption: :simple_tls
departmental_cn: 'USERNAME'
departmental_pw: 'PASSWORD'
theme: 'umn'
ELASTICSEARCH_URL: 'elastic.umn.edu'
wkhtmltopdf_binary_path: 'PATH'
DEFAULT_URL_HOST: 'yourstudyfinder.example.com' # Used in email links/URLs

Loading trials

$ rake studyfinder:ctgov:reload_all
# defaults to 4 days previous
$ rake studyfinder:ctgov:load

# specify the number of days previous as a parameters (10 days in this example)
$ rake studyfinder:ctgov:load[10]
$ rake studyfinder:trials:reindex

Themes

StudyFinder offers a CSS-based theme system. You will find example files in /app/assets/stylesheets/theme. A very basic knowledge of CSS is enough to adapt the examples for branded color schemes, etc. Users experienced in CSS/SASS can achieve a great deal of customization here without touching any of the Ruby/Rails code.

StudyFinder uses Bootstrap 4, so Bootstrap mixins, classes, etc. are also available to and can be customized by your theme. Bootstrap Documentation

Some of the examples include references to images. E.g., the 'brand' class defines the logo image that appears at the upper left of every page:

.brand {
    background: image-url("logo.png");
    ...
}

Any images referenced in your theme CSS should be located in /app/assets/images.

Themes are the recommended method for customizing the appearance of the site. Users with Ruby/Rails experience can change the template files for infinite customization, but as with any open-source project, local changes to the code make pulling updates much more difficult.

Other Site Customization

Many aspects of your site can be customized from the site itself, via the admin interface. To access the admin interface, LDAP authentication must be configured. Click "Sign In" at the bottom of the home page, and then you will see an "Admin" link on the navbar. The first option, "System Administration", allows you to manage what fields do and don't appear on some screens, set label text, define the location search term for data loads from clinicaltrials.gov, and much more.

ElasticSearch synonyms

The default trial search configuration uses a query-time synonym_graph filter. It supports multi-term synonyms, e.g. 'caloric restrictions' and 'low calorie diet'. When trials are indexed, ElasticSearch creates the search analyzer for this. You do not have to re-index trials if the synonyms are updated, because it is a query-time filter.

The default location for synonyms is in an array defined in 'lib/modules/trial_synonyms.rb'. Updates to the synonyms can be picked up by restarting the Rails service.

Alternately, you can use a synonyms file. To use a synonyms file, use the configuration option:

  config.synonyms_path = '/usr/share/elasticsearch/config/analysis/synonyms.txt'

This file is on the ElasticSearch server, not part of the Rails application. In deployed environments, you will need to copy your synonyms file to this location. This isn't necessary in the development docker container; just put your file in 'config/analysis/'. Docker-compose which mounts 'config/analysis' within the Rails app to the above path in the ElasticSearch container. This allows easier access for modifying synonyms during development, as you can work with them directly in 'config/analysis/synonyms.txt' within the Rails app structure.

Trademark

"StudyFinder" is a registered trademark of the University of Minnesota. Your instance of StudyFinder should retain the official StudyFinder logo that appears at the upper right of each page. This is an SVG image and can be styled with your institution's colors. By default it uses the main and secondary colors that are specified in the theme CSS file: 

$school_main_color: #7a0019;
$school_secondary_color: #ffd75f;

Embed Widget

The search screen within StudyFinder has the ability to be embedded into other websites. To do this add the following snippet to any other sites wanting to embed the search capability of StudyFinder.

<iframe src="https://studyfinder.url/embed" width="100%" height="350" frameborder="0"></iframe>

Adding Captcha to email forms (optional)

If you would like to add a captcha to the contact forms, follow the steps below.

  1. Go to https://www.google.com/recaptcha/admin and obtain a reCAPTCHA API key.
  2. Put the site key and secret key into the application.yml file as variables. 
    RECAPTCHA_SITE_KEY: 'site_key_from_google'
RECAPTCHA_SECRET_KEY: 'secret_key_from_google'
  3. Go to the admin section and turn on the "Add Captcha to email forms" option and save.
  4. Verify that captcha is now setup on forms.