SPARCRequest Configuration Guide

Table of Contents:

1. Database Settings

1.1 Adapters

SPARCRequest has been designed to use the mysql2 adapter, however fairly extensive testing has also been done with the sqlite3 adapter. No postgresql adapters have been tested with the system, however they may well work. If you desire to use any adapter other than mysql2 heavy testing is advised, starting with the test suite to attempt to probe for issues.

1.2 Environments

SPARCRequest Rails environment configurations are mostly standard. However the following method:

config.action_mailer.default_url_options

will need to be set in each environment according to the sending url. Also in the development environment the letter_opener gem is utilized and thus the option:

config.action_mailer.delivery_method = :letter_opener

should be set.

In the production environment ExceptionNotifier is setup, and its options will need to be set to the individuals that you would like to send and receive notifications when exceptions occur in production, i.e.:

config.middleware.use ExceptionNotifier, sender_address: 'no-reply@example.com', exception_recipients: ['user@example.com']

2. Settings & Configuration (Most of the Settings can now be managed from SPARCAdmin module by Site Admin users)

SPARCRequest utilizes a number of settings to allow you to customize content and enable or disable functionality based on your institution's needs. These settings are stored in the settings database table and are populated from config/defaults.json.

We highly recommend saving your environment's settings to avoid losing your settings. To do this, first run the following commands:

# application.yml will hold the majority of your stored setting values cp config/application.yml.example config/application.yml # epic.yml will hold your epic configuration values cp config/epic.yml.example config/epic.yml # ldap.yml will hold your ldap configuration values cp config/ldap.yml.example config/ldap.yml

These files will hold your setting values. When the application imports settings, it will prioritize the values specified in these files for your current environment. Note: You may add or remove environemnts from these files as needed.

To manually import new settings, run the following command:

rake data:import_settings

To entirely refresh your settings, run the following command:

rake data:regenerate_settings

2.1 Generic Settings

SPARCRequest has many settings that are used internally to customize content and configurations.

Emails

• send_emails_to_real_users: This tells the application whether or not to send emails to users. When turned off, emails will be generated in the browser but not sent. This should be turned off in development environments.

• send_authorized_user_emails: This determines whether the application will send emails to all authorized users with View or greater rights.

• root_url: This is the root URL for the application for use in emails.

• dashboard_link: This is the URL of SPARCDashboard for use in emails.

• admin_mail_to: This field will overwrite the admin user mailers in the application to instead mail to this address. This is overwritten in development/testing/staging environments in order to prevent real emails from being sent out to admin users.

• default_mail_to: This field will overwrite the mailers in the application to instead mail to this address. This is overwritten in development/testing/staging environments in order to prevent real emails from being sent out to general users.

• listserv_mail_to: This is the emails of users who are emailed by the Listserv link in the footer.

• new_user_cc: This field will overwrite the new user mailers in the application to instead cc to this address. This is overwritten in development/testing/staging environments in order to prevent real emails from being sent out to general users.

• no_reply_from: This is the email that will appear as the sender of all emails sent from the application.

Links and URLs

• about_sparc_url: This is the URL linked to by the About SPARCRequest button on the homepage.

• header_link_1: This is the URL for the Organization Logo - the left image in the SPARCRequest header.

• header_link_3: This is the URL for the Institution Logo - the right image in the SPARCRequest header.

• navbar_links: This defines the links that appear in the header navbar, including SPARCRequest, SPARCDashboard, SPARCCatalog, SPARCReport, SPARCForms, SPARCAdmin, SPARCInfo, SPARCFunding (optional), SPARCFulfillment (optional).

• For example, below is the MUSC navbar setting:

• {"sparc_request"=>["SPARCRequest", "https://sparc.musc.edu/"], "sparc_dashboard"=>["SPARCDashboard", "https://sparc.musc.edu/dashboard"], "sparc_fulfillment"=>["SPARCFulfillment", "https://sparc-fulfillment.musc.edu"], "sparc_catalog"=>["SPARCCatalog", "https://sparc.musc.edu/catalog_manager"], "sparc_report"=>["SPARCReport", "https://sparc.musc.edu/reports"], "sparc_forms"=>["SPARCForms", "https://sparc.musc.edu/surveyor/responses"], "sparc_admin"=>["SPARCAdmin", "https://sparc.musc.edu/admin/applications"], "sparc_info" => ["SPARCInfo", "https://sparcrequest.atlassian.net/wiki/spaces/RD/overview"]}

• Other Links: New links may be added by using the following syntax: \"key\": [\"Link Text\", \"Full URL\"].

Statuses

• updatable_statuses: This defines the statuses that a SubServiceRequest can be updated from. Any other statuses are considered un-updatable.

• finished_statuses: This defines the statuses in which a SubServiceRequest is considered complete. When in these statuses, SubServiceRequests can't be updated. New services from those organizations will be added to new SubServiceRequests.

Other Settings

• host: This is the host domain of your instance of SPARCRequest.

• site_admins: This is a list of users who will have full access to the Survey/Form builder and SPARCForms.

• use_indirect_cost: This determines how the application displays costs to users. If turned on, then in addition to direct costs and direct cost subtotals, users will also see indirect costs and indirect cost subtotals, and indirect costs will also be included in the grand total. If turned off, then indirect costs will not be displayed to users, nor included in the grand total.

• use_separate_audit_database: This determines whether the application will store audits in a separate datebase. The application expects this database to be named audit_#{Rails.env}.

• wkhtmltopdf_location: This is a customizable path pointing to the binary for the wkhtmltopdf gem which is used to generate PDFs of HTML content. The default value provided by the gem is /usr/local/bin/wkhtmltopdf.

2.2 Configuring Omniauth

Your institution may opt to use Omniauth authentication plugins such as CAS and Shibboleth for user authentication in SPARCRequest. Only CAS and Shibboleth are supported at this time, but support for other Omniauth plugins may be implemented.

Omniauth Configuration

• use_cas: This determines whether the application will allow users to log in using CAS.

• use_cas_only: This determines whether the application will only allow users to log in using CAS. This has lower precedence than use_shibboleth_only when both are enabled.

• use_shibboleth: This determines whether the application will allow users to log in using Shibboleth.

• use_shibboleth_only: This determines whether the application will only allow users to log in using Shibboleth. This has higher precedence than use_shibboleth_only when both are enabled.

2.3 Configuring LDAP

Your institution may opt to use LDAP for managing identities in SPARCRequest. You should save your environment's LDAP settings by overriding the values in config/ldap.yml.

LDAP Configuration

• use_ldap: This determines whether the authorized user search will attempt to connect to an LDAP server. If turned off, it will simply search the database.

• lazy_load_ldap: When enabled, the database will return only LDAP Identities found in the database and will not create new entries. When disabled, if an LDAP Identity is not found in the database, a record will be created for that user and returned.

• suppress_ldap_for_user_search: Allow the use of LDAP but suppress its use within the authorized user search.

LDAP Fields

• ldap_host: This is the host server for your institution's LDAP.

• ldap_port: This is the port at which LDAP is accessible on the server.

• ldap_base: This is the LDAP base suffixes for your institution's LDAP.

• ldap_encryption: This is the type of encryption present on your institution's LDAP.

• ldap_domain: This is the domain suffix found on the ldap_uid of your users. (Ex: The domain of anc63@musc.edu is musc.edu)

• ldap_uid: This is the key in your institution's LDAP records that corresponds to the uid of a given user.

• ldap_last_name: This is the key in your institution's LDAP records that corresponds to the last name/surname of a given user.

• ldap_first_name: This is the key in your institution's LDAP records that corresponds to the first name/given name of a given user.

• ldap_email: This is the key in your institution's LDAP records that corresponds to the email of a given user.

• ldap_auth_username: This is an optional username to access your institution's LDAP.

• ldap_auth_password: This is an optional password to access your institution's LDAP.

• ldap_filter: This is an optional filter that allows you to control how LDAP searches for an identity. Filter documentation can be found here.