.. _qatrack-config: Configuring a QATrack+ Installation =================================== QATrack+ Local Settings ----------------------- Local settings allow you to override the default QATrack+ settings to better meet your clinics needs. The most important settings are explained below. These settings should be defined in a `local_settings.py` file in the main directory (same directory as `settings.py`) .. _reload-config: After configuration changes ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Any time you change a setting in local_settings.py, you need to restart the QATrack+ application either by restarting Apache or restarting the CherryPy Windows Service and you also need to restart Django Q. Restarting QATrack+ on Linux ............................ .. code-block:: console sudo service apache2 restart sudo supervisorctl reread sudo supervisorctl update Restarting QATrack+ on Windows .............................. Open a PowerShell Window and enter the following commands: .. code-block:: console cd C:\deploy .\venvs\qatrack31\Scripts\Activate.ps1 cd qatrackplus python QATrack3CherryPyService.py restart Stop-ScheduledTask -TaskName "QATrack+ Django Q Cluster" Start-ScheduledTask -TaskName "QATrack+ Django Q Cluster" Mandatory Settings ~~~~~~~~~~~~~~~~~~ DEBUG Setting ............. When deploying your site for clinical use, you should set: .. code-block:: python DEBUG = False however, when you are experiencing issues getting your site deployed, setting: .. code-block:: python DEBUG = True will show you a detailed error traceback which can be used to diagnose any issues. .. danger:: It is important to not use DEBUG = True during normal service as it may affect site performance and security. Allowed Host Setting .................... On Linux, set allowed hosts either to your server name or IP address (e.g. for Apache): .. code-block:: python ALLOWED_HOSTS = ['52.123.4.9'] On Windows using CherryPy/IIS (or if you are running QATrack+ behind a reverse proxy on Linux): .. code-block:: python ALLOWED_HOSTS = ['127.0.0.1', 'localhost'] HTTP or HTTPS Setting ..................... In order for urls to use the correct protocol for links, set `HTTP_OR_HTTPS` to the appropriate protocol. .. code-block:: python HTTP_OR_HTTPS = 'http' # when using http for your site (default) # -or - HTTP_OR_HTTPS = 'https' # when using https/ssl for your site .. _databases: DATABASES Setting ................. The database setting is covered in more detail in the `Django documentation `__ as well as the QATrack+ deployment documentation. .. code-block:: python DATABASES = { 'default': { 'ENGINE': 'django.db.backends.postgresql', 'NAME': 'qatrackplus', 'USER': 'qatrack', 'PASSWORD': 'qatrackpass', 'HOST': 'localhost', 'PORT': '5432', }, 'readonly': { 'ENGINE': 'django.db.backends.postgresql', 'NAME': 'qatrackplus', 'USER': 'qatrack_reports', 'PASSWORD': 'qatrackpass', 'HOST': 'localhost', 'PORT': '5432', } } If you are using SQL Server and the SQL Reports feature, you may also need to set `AUTOCOMMIT = False` for your readonly configuration (see the `USE_SQL_REPORTS` setting below). Cache Settings ~~~~~~~~~~~~~~ By default QATrack+ stores cached pages and values on disk in the directory `qatrack/cache/cache_data/` but this can be changed by copying the Python dictionary below into your `local_settings.py` file: .. code-block:: python CACHES = { 'default': { 'BACKEND': 'django.core.cache.backends.filebased.FileBasedCache', 'LOCATION': '/path/to/your/desired/cache/data/location/', 'TIMEOUT': 24*60*60, # cache timeout of 24hours } } Generally you shouldn't need to change this unless you have concerns about disk usage. Time Zone Settings ~~~~~~~~~~~~~~~~~~ By default QATrack+ is configured to use North American Eastern Standard Time so you will need to adjust this to reflect your local time zone. In your *local_settings.py* file add a line like the following: .. code-block:: python TIME_ZONE = 'America/Toronto' where 'America/Toronto' is replaced with your local timezone (e.g. `TIME_ZONE = 'Australia/Sydney'`. If you are unsure, you can find a list of `valid timezones on Wikipedia `_. Icon Settings ~~~~~~~~~~~~~ By default QATrack+ will show icons to indicate the pass/fail or due/overdue/not due status of tests and test lists. Examples of the icons can be seen on `BitBucket `_ To override the default settings, copy the following Python dictionary to your `local_settings.py` file and change the relevant setting to True/False. .. code-block:: python ICON_SETTINGS = { 'SHOW_STATUS_ICONS_PERFORM': True, 'SHOW_STATUS_ICONS_LISTING': True, 'SHOW_STATUS_ICONS_REVIEW': True, 'SHOW_STATUS_ICONS_HISTORY': False, 'SHOW_REVIEW_ICONS': True, 'SHOW_DUE_ICONS': True, } * `SHOW_STATUS_ICONS_PERFORM` controls whether the icons are shown when a user is performing a test list. * `SHOW_STATUS_ICONS_LISTING` controls whether icons are shown on listings pages which show the results of the last QC session. (Default True) * `SHOW STATUS_ICONS_REVIEW` controls whether the icons are shown when a user is reviewing a test list. (Default True) * `SHOW STATUS_ICONS_HISTORY` controls whether the icons are shown for historical results when a user is performing or reviewing a test list. (Default False) * `SHOW_REVIEW_ICONS` control whether to show warning icon for unreviewed test lists. (Default True) * `SHOW_DUE_ICONS` control whether to show icons for the due status of test lists. (Default True) Tolerance Naming Settings ~~~~~~~~~~~~~~~~~~~~~~~~~ By changing the following settings you can alter the phrasing that QATrack+ uses for indicating whether a test is passing/failing. The `TEST_STATUS_DISPLAY_SHORT` settings are used when performing a test list and the `TEST_STATUS_DISPLAY` settings are used in notifications and when displaying historical results. .. code-block:: python TEST_STATUS_DISPLAY = { 'action': "Action", 'fail': "Fail", 'not_done': "Not Done", 'done': "Done", 'ok': "OK", 'tolerance': "Tolerance", 'no_tol': "No Tol Set", } TEST_STATUS_DISPLAY_SHORT = { 'action': "ACT", 'fail': "Fail", 'not_done': "Not Done", 'done': "Done", 'ok': "OK", 'tolerance': "TOL", 'no_tol': "NO TOL", } The meaning of the individual keys is as follows: * `action`: Test is failing or at action level (shown to users with permission to view Refs/Tols) * `fail`: Test is failing or at action level (shown to users without permission to view Refs/Tols) * `not_done`: Test was not completed * `done`: Test was completed * `ok`: Test is passing / within tolerance * `tolerance`: The test is at tolerance (shown to users with permission to view Refs/Tols) * `no_tol`: No tolerances set for this test Other Settings ~~~~~~~~~~~~~~ .. _accounts_password_reset: When `ACCOUNTS_PASSWORD_RESET = True` users will be able to reset or change their passwords on their own. This only applies to the normal QATrack+ authentication backend, and not the LDAP or ADFS backends. Default is `True`. .. _accounts_self_register: ACCOUNTS_SELF_REGISTER ...................... When `ACCOUNTS_SELF_REGISTER = True` anonymous users are able to register themselves for accounts. Default is `False`. .. _accounts_clean_username: ACCOUNTS_CLEAN_USERNAME ....................... When `ACCOUNTS_CLEAN_USERNAME` is set to callable it will be used to transform any username that is to be authenticated. The most common scenario for this setting it is for example to set `def ACCOUNTS_CLEAN_USERNAME(username): return username.lower()` which makes all logins lowercase. Note in this case, the user can enter `SoMeUsErName` and it will be authenticated as `someusername`. Default is `ACCOUNTS_CLEAN_USERNAME = False`. .. _autosave_days_to_keep: Set `AUTOSAVE_DAYS_TO_KEEP` to control the maximum number of days that auto-saved QC data will be kept for. The default settings is 30 days. CHROME_PATH ........... Set `CHROME_PATH` to the Chrome/Chromium executable for generating PDF reports. For example .. code-block:: python CHROME_PATH = '/usr/bin/chromium-browser' # default # - or - CHROME_PATH = 'C:/path/to/chromium.exe' # on Windows CATEGORY_FIRST_OF_GROUP_ONLY ............................ When `CATEGORY_FIRST_OF_GROUP_ONLY = True`, then the category will only be shown for the first test of a consecutive group of tests sharing the same category, otherwise the category will be shown next to each test line when performing QC. COMPOSITE_AUTO_FORMAT ..................... When `COMPOSITE_AUTO_FORMAT = True` (default) calculation procedures will be auto formatted with `Black `_ . This leaves everyones code in a consistent format making stylistic differences when reading code a non-issue. Set to `False` to tell QATrack+ to leave your code alone! CONSTANT_PRECISION (deprecated. Use DEFAULT_NUMBER_FORMAT instead) .................................................................. Set the `CONSTANT_PRECISION` setting to adjust the precision for which :ref:`Constant test type ` values are displayed. (default 8) DEFAULT_NUMBER_FORMAT ..................... Default formatting string to be used for Composite & Constant number formatting (can be overridden on a test by test basis). Set to a Python style string format for displaying numerical results. Use e.g. %.2F to display as fixed precision with 2 decimal places, or %.3E to show as scientific format with 3 significant figures, or %.4G to use 'general' formatting with up to 4 significant figures. (Note this does not affect the way other values are calculated, only the way composite and constant test values are *displayed*. For example a constant test with a value of 1.2345 and a format of %.1f will be displayed as 1.2, but the full 1.2345 will be used for calculations). Note you may also use "new style" Python string formatting: see https://pyformat.info/ for examples. .. code-block:: python DEFAULT_NUMBER_FORMAT = "%.3f" # 3 decimal place fixed precision using "Old" style formatting DEFAULT_NUMBER_FORMAT = "{:.3f}" # 3 decimal place fixed precision using "New" style formatting DEFAULT_NUMBER_FORMAT = "{:.4E}" # 5 sig fig scientific notation using "New" style formatting DEFAULT_WARNING_MESSAGE ....................... Set `DEFAULT_WARNING_MESSAGE = "Your custom message"` to change the default warning message that will be shown when a performed test is at action level. If `DEFAULT_WARNING_MESSAGE = ""` then the default will be to not show any warning message when a test is at action level. FORCE_SCRIPT_NAME, LOGIN_REDIRECT_URL, LOGIN_URL, STATIC_URL, MEDIA_URL, UPLOADS_URL .................................................................................... If you deploy QATrack+ at a non root url (e.g. http://5.5.5.5/qatrack/) then you need to set these settings as follows: .. code-block:: python FORCE_SCRIPT_NAME = '/qatrack' LOGIN_REDIRECT_URL = 'qatrack/' LOGIN_URL = "/qatrack/accounts/login/" If you've also changed the directory IIS is serving static media from, you may need to adjust the static and media urls as well: .. code-block:: python # just an example, change according to how you have configured IIS MEDIA_URL = '/qatrack_media/' UPLOADS_URL = MEDIA_URL + 'uploads/' STATIC_URL = '/qatrack_static/' MAX_TESTS_PER_TESTLIST ...................... Sets the maximum number of tests per test list. Default is `MAX_TESTS_PER_TESTLIST = 200` NHIST ..... Adjusts the number of historical test results to show when reviewing/performing QC. Default is `NHIST = 5`. ORDER_UNITS_BY .............. Set `ORDER_UNITS_BY = 'name'` in your `local_settings.py` file in order to order units by `name` rather than `number` PING_INTERVAL_S ............... Controls how often (in seconds) the server is "pinged" when performing QC or entering service log data. Set to `PING_INTERVAL_S = 0` to disable the ping check. Default is `PING_INTERVAL_S = 5` REVIEW_DIFF_COL ............... Set `REVIEW_DIFF_COL = True` to include a difference column when reviewing test list results. This column shows the difference between a test value and its reference value. .. _review_bulk: REVIEW_BULK ........... Set `REVIEW_BULK = False` to disable the :ref:`Bulk Review ` feature which allows users to update the review and approval status of multiple test list instances at the same time. .. _setting_sl_allow_blank_service_area: SL_ALLOW_BLANK_SERVICE_AREA ........................... Set `SL_ALLOW_BLANK_SERVICE_AREA = True` to allow users to create a ServiceEvent with a blank ServiceArea set. When a Service Event is saved without a ServiceArea explicitly set, the ServiceArea will be set to "Not Specified". .. _setting_sl_allow_blank_service_type: SL_ALLOW_BLANK_SERVICE_TYPE ........................... Set `SL_ALLOW_BLANK_SERVICE_TYPE = True` to allow users to create a ServiceEvent with a blank ServiceType set. When a Service Event is saved without a ServiceType explicitly set, the ServiceType will be set to "Not Specified". TESTPACK_TIMEOUT ................ Change the number of elapsed seconds before exporting a TestPack will time out. Default is 30. USE_SQL_REPORTS ............... Set `USE_SQL_REPORTS` to `True` in order to enable the SQL Query tool. Note if you are using SQL Server for your database, you may also need to set `AUTOCOMMIT = False` for your readonly database user: .. code-block:: python DATABASES = { 'default': { # default connection settings... }, 'readonly': { 'ENGINE': 'sql_server.pyodbc', 'AUTOCOMMIT': False, # rest of db settings } } USE_X_FORWARDED_HOST .................... Set `USE_X_FORWARDED_HOST = True` when running QATrack+ behind a reverse proxy and set to False for whenever you are not running behind a reverse proxy e.g. Set to True for CherryPy/IIS and False for Apache/mod_wsgi or development work. SESSION Settings ~~~~~~~~~~~~~~~~ These settings control how quickly users are automatically logged out of an active browser session. `SESSION_COOKIE_AGE` specifies how long (in seconds) a user can use a browser session without having to log in again (default 2 weeks). However, if `SESSION_SAVE_EVERY_REQUEST` is `True` the session age will be reset every time a user is active and hence allows them to stay logged in indefinitely. .. code-block:: python SESSION_COOKIE_AGE = 14 * 24 * 60 * 60 SESSION_SAVE_EVERY_REQUEST = True .. _config_email: Configuring Email for QATrack+ ------------------------------ QATrack+ email settings QATrack+ has the ability to send emails :ref:`email notifications ` when tests are at action or tolerance levels. In order for this to function you need access to an SMTP server that can send the emails for you. In order to override the default settings, in your local_settings.py file you should set the following variables appropriately. Admin Email ~~~~~~~~~~~ Who should be emailed when internal QATrack+ errors occur: .. code-block:: python ADMINS = ( ('Admin Name', 'admin.email@yourplace.com'), ) MANAGERS = ADMINS Default Sender ~~~~~~~~~~~ The default "from" address for notification emails (e.g. password reset requests): .. code-block:: python DEFAULT_FROM_EMAIL = "email@yourplace.com" This may need to be the same as EMAIL_HOST_USER depending on server settings Email host settings ~~~~~~~~~~~~~~~~~~~ * `EMAIL_HOST` should be set to the SMTP host you are using (e.g. 'smtp.gmail.com' or 'smtp.mail.your.hospital') * `EMAIL_HOST_USER` this is the default email address of the account to access the SMTP server * `EMAIL_HOST_PASSWORD` this is the default account of the account to access the SMTP server * `EMAIL_USE_TLS` set to True to use secure connection when connecting to the server * `EMAIL_PORT` set to the port number to connect to the smtp server on (25 if `EMAIL_USE_TLS` is False, 587 if True) * `EMAIL_FAIL_SILENTLY` set to False to see error tracebacks when sending an email fails. (should only be used for debugging) Note that `EMAIL_HOST_USER` and `EMAIL_HOST_PASSWORD` can be set to None or "" if no authentication is required. An example of these settings for a secure connection is shown here (for gmail): .. code-block:: python EMAIL_HOST = "smtp.gmail.com" EMAIL_HOST_USER = 'randle.taylor@gmail.com' EMAIL_HOST_PASSWORD = 'my_very_secure_password' EMAIL_USE_TLS = True EMAIL_PORT = 587 and for an unsecured connection: .. code-block:: python EMAIL_HOST = "MYHOSPITALSMTPSERVER" EMAIL_HOST_USER = None EMAIL_HOST_PASSWORD = None EMAIL_USE_TLS = False EMAIL_PORT = 25 .. _email_notification_settings: Notification specific settings ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ These settings allow you to override the default notification settings in your local_settings.py file: * `EMAIL_NOTIFICATION_SENDER` email address to use in QATrack+ emails "From" address * `EMAIL_NOTIFICATION_SUBJECT_TEMPLATE` allows you to override the default template to use for rendering the email subject line (see below) * `EMAIL_NOTIFICATION_TEMPLATE` allows you to override the default template to use for rendering the email body (see below) * (deprecated) `EMAIL_NOTIFICATION_USER` allows you to use a diferent user from the default set above (set to None to use `EMAIL_HOST_USER`). This setting is no longer used, set `EMAIL_HOST_USER` instead. * (deprecated) `EMAIL_NOTIFICATION_PWD` password to go along with `EMAIL_NOTIFICATION_USER`. This setting is no longer used, set `EMAIL_HOST_PASSWORD` instead. An example of these settings is shown here: .. code-block:: python #----------------------------------------------------------------------------- # Email and notification settings EMAIL_NOTIFICATION_USER = None EMAIL_NOTIFICATION_PWD = None EMAIL_NOTIFICATION_SENDER = "Your Custom Name Here" EMAIL_NOTIFICATION_SUBJECT_TEMPLATE = "my_custom_subject_template.txt" EMAIL_NOTIFICATION_TEMPLATE = "my_custom_html_email.html" Email & Subject templates ~~~~~~~~~~~~~~~~~~~~~~~~~ Emails are generated using `the Django template language `__ with the following context available: * `test_list_instance` The TestListInstance object containing information about the test list and unit where the tests were being performed. * `failing_tests` a `queryset `__ of all tests that failed. * `tolerance_tests` a `queryset `__ of all tests that are at tolerance level. To create your own templates, use the examples below as a starting point and save them in the qatrack/notifications/templates/ directory and set the filenames for the `TEMPLATE` settings above. An example subject template is shown below .. code-block:: django {{test_list_instance.work_completed|date:"DATE_FORMAT"}} - {{test_list_instance.unit_test_collection.unit.name }}, {{test_list_instance.test_list.name}} - {% if failing_tests %} Tests at Action: {{failing_tests.count}} {% endif %} {% if tolerance_tests %} Tests at Tolerance: {{tolerance_tests.count}} {% endif %} The default HTML email template is shown here: .. code-block:: html {% load comments %} Notifications for {{test_list_instance.test_list.name}}
 
Notifications for {{test_list_instance.test_list.name}}

Hello

You are receiving this notice because one or more tests were at tolerance or action levels for the following test list instance:

{% if test_list_instance.comments.exists %} {% endif %}
Test List: {{test_list_instance.test_list.name}}
Unit: {{test_list_instance.unit_test_collection.unit.name}}
Date: {{ test_list_instance.work_completed }}
Link: {% if 'http' not in domain %}http://{% endif %}{{ domain }}{{ test_list_instance.get_absolute_url }}
Comments: {% render_comment_list for test_list_instance %}
{% for test_instance in failing_tests %} {% if test_instance.comment %} {% endif %} {% endfor %}
Failing Tests
Test Value Reference Tolerance
{{test_instance.unit_test_info.test.name}} {{test_instance.value_display}} {{test_instance.reference}} {{test_instance.tolerance}}
{{ test_instance.comment }}
{% for test_instance in tolerance_tests %} {% if test_instance.comment %} {% endif %} {% endfor %}
Tests at Tolerance
Test Value Reference Tolerance
{{test_instance.unit_test_info.test.name}} {{test_instance.value_display}} {{test_instance.reference}} {{test_instance.tolerance}}
{{ test_instance.comment }}
Sent by QATrack+
 
An example plain text email template is shown below .. code-block:: text === Notifications for {{test_list_instance.test_list.name}} === Test List : {{test_list_instance.test_list.name}} Unit : {{test_list_instance.unit_test_collection.unit.name}} Date : {{test_list_instance.work_completed }} {% if failing_tests %} Failing Tests ============= {% for test_instance in failing_tests %} Test : {{test_instance.unit_test_info.test.name}} Value : {{test_instance.value_display}} Ref. : {{test_instance.reference}} Tol. : {{test_instance.tolerance}} {% endfor %} {% endif %} {% if tolerance_tests %} Tests at Tolerance ================== {% for test_instance in tolerance_tests %} Test : {{test_instance.unit_test_info.test.name}} Value : {{test_instance.value_display}} Ref. : {{test_instance.reference}} Tol. : {{test_instance.tolerance}} {% endfor %} {% endif %} .. _settings_ad: Active Directory Settings ~~~~~~~~~~~~~~~~~~~~~~~~~ QATrack+ allows you to use an Active Directory (AD) server for User authentication. In order to use Active Directory you need to set up the following settings: AUTHENTICATION_BACKENDS ....................... In order to use one of the Active Directory backends, you need to copy the `AUTHENTICATION BACKENDS` setting to your local_settings.py and uncomment the :ref:`backend ` you want to use e.g.: .. code-block:: python AUTHENTICATION_BACKENDS = [ 'qatrack.accounts.backends.QATrackAccountBackend', 'qatrack.accounts.backends.ActiveDirectoryGroupMembershipSSLBackend', # 'qatrack.accounts.backends.WindowsIntegratedAuthenticationBackend', # 'qatrack.accounts.backends.QATrackAdfsAuthCodeBackend', ] General AD Settings ................... .. code-block:: python AD_DNS_NAME = 'ad.subdomain.maindomain.on.ca' # DNS Name AD_LU_ACCOUNT_NAME = "sAMAccountName" # AD Lookup account name property AD_LU_MAIL = "mail" # AD Lookup account email property AD_LU_SURNAME = "sn" # AD Lookup account surname property AD_LU_GIVEN_NAME = "givenName" # AD Lookup account given name property AD_LU_MEMBER_OF = "memberOf" # AD Lookup group membership property AD_SEARCH_DN = "" # eg "dc=ottawahospital,dc=on,dc=ca" AD_NT4_DOMAIN = "" # Network domain that AD server is part of AD_CERT_FILE = '/path/to/your/cert.txt' AD_CLEAN_USERNAME_STRING = '' # if your AD usernames are returned as e.g. "foo/jsmith" then # setting `AD_CLEAN_USERNAME_STRING = 'foo/'` will strip the `foo/` prefix # off the username, so the QATrack+ username will just be 'jsmith' AD_CLEAN_USERNAME = None # define a function called AD_CLEAN_USERNAME in local_settings.py if you # wish to clean usernames before sending to ldap server e.g. # def AD_CLEAN_USERNAME(username): return username.lower() Non-SSL AD Connection Settings ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If using a non-SSL connection use these .. code-block:: python AD_LDAP_PORT = 389 AD_LDAP_URL = 'ldap://%s:%s' % (AD_DNS_NAME, AD_LDAP_PORT) AD_LDAP_USER = '' AD_LDAP_PW = '' SSL AD Connection Settings ^^^^^^^^^^^^^^^^^^^^^^^^^^ If using SSL use these: .. code-block:: python AD_LDAP_PORT = 636 AD_LDAP_URL = 'ldaps://%s:%s' % (AD_DNS_NAME,AD_LDAP_PORT) AD_LDAP_USER = '' AD_LDAP_PW = '' More information on Active Directory is available here: :ref:`Active Directory `.