Configuration¶
TruenNTH Shared Services can be configured in a number of fashions, to support a variety of use cases.
Three primary mechanisms are in place to setup the system as desired:
Flask Configuration Files¶
Flask configuration files (.cfg
) are simple python files used to set Flask configuration parameters.
application.cfg¶
This primary configuration file lives in the instance source directory.
See README for initial setup of application.cfg
.
Only values unique to a particular install belong in application.cfg including:
- passwords
- keys / secrets
- filesystem paths or local connection details
All others should likely be handled by Site Persistence.
Values with defaults are typically defined in the portal.config.BaseConfig
class. Most are self explanatory or include inline comments for clarification.
Of special note, the one used to control which set of values are pulled in by Site Persistence.
PERSISTENCE_DIR:
See also Site Persistence, this controls which persistence directory the
`FLASK_APP=manage.py flask sync` command uses to load persistence data
and build the `site.cfg` file. The value is relative to the
`portal/config` directory.
For TrueNTH:
PERSISTENCE_DIR='gil'
For ePROMs:
PERSISTENCE_DIR='eproms'
site.cfg¶
This configuration file also lives in the instance source directory, but unlike application.cfg, it is managed by Site Persistence. It houses the configuration variables used to define the look of the site, such as those use to differentiate ePROMs from TrueNTH.
A few worthy of special mention for the task of customizing Shared Services.
REQUIRED_CORE_DATA:
Set to control what portions of data are considered *required* prior
to allowing the user to transition beyond initial_queries. Expects
a list, with the following options:
REQUIRED_CORE_DATA = ['name', 'dob', 'role', 'org', 'clinical', 'tou']
PORTAL_STYLESHEET:
Define which stylesheet to include. Defaults to 'css/portal.css'
For ePROMs:
PORTAL_STYLESHEET = 'css/eproms.css'
To update the site.cfg
file contents, edit the
site_persistence_file.json
file or use the FLASK_APP=manage.py flask export-site
command and commit the changed site_persistence_file.json
to the
appropriate repository.
base.cfg¶
An optional configuration file loaded before application.cfg, useful for setting infrastructure-specific defaults.
Site Persistence¶
In order to handle the migration of site specific data, one can generate or import a persistence file, housing details such as:
- business rules defining when interventions should be presented to users
- customization of intervention text
- organizations and clinics on the site
The portal.SitePersistence
class manages the import and export of
the site.cfg
configuration file as well as a
number of database tables holding significant data required for a rich
experience. This should never include any patient or personal data, but
will include codified business rules and required data to support them.
Database tables included:
- AccessStrategies
- AppText
- CommunicationRequest
- Interventions
- Organizations
- Questionnaires
- QuestionnaireBanks
- ScheduledJobs
Both importing and exporting use the value of PERSISTENCE_DIR
.
Its value is initially looked for as an environment variable, and if not
found, the configuration value of ‘GIL’ is used. (With ‘GIL’ set, the gil
configuration directory is used, otherwise, eproms).
Export¶
Site persistence files can be generated in the PERSISTENCE_DIR
. See
above for correct setting. To generate persistence files from current
database values, execute:
```FLASK_APP=manage.py flask export-site```
Import¶
As a final step in the seed
process, site persistence brings the
respective database tables in sync, and generates the site.cfg config file:
`FLASK_APP=manage.py flask seed`
Detailed logging will inform the user of changes made.
Note
It may be wise to back up the existing database prior to running python
manage.py seed
in the unlikely event of unwanted overwrites or deletes.
AppText¶
To avoid near duplication of templates needing only a few minor string changes,
the portal.models.AppText
class (and its surrogate apptext
database
table), provide a mechanism for customizing individual strings.
In a template, in place of a static string, insert a jinja2 variable string calling the app_text function, including the unique name of the string to be customized. For example, in the portal.templates.layout.html file, the value of the title string is imported via:
<title>{{ app_text('layout title') }}</title>
The value for such an AppText can be manually inserted in the database, or added to the site persistence file. Such an entry looks like:
{
"custom_text": "Movember ePROMs",
"name": "layout title",
"resourceType": "AppText"
},
AppText can also handle positional arguments as well as references to configuration values to fill in dynamic values within a string. The positional arguments are zero indexed, and must be defined when the template is rendered (i.e. JavaScript variables will not be properly defined until the script is evaluated within the browser, and will therefore not work).
For example, given the application has the configuration
value USER_APP_NAME
set to TrueNTH
and the following:
AppText(name='ex', custom_text='Welcome to {config[USER_APP_NAME]}, {0}. {1} {0}')
A template including:
<p>{{ app_text('ex', 'Bob', 'Goodbye') }}</p>
Would render:
<p>Welcome to TrueNTH, Bob. Goodbye Bob</p>