.. _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`) .. note:: 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. 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'] 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': 'qatrack', 'USER': 'qatrack', 'PASSWORD': 'qatrackpass', 'HOST': 'localhost', 'PORT': '5432', } } 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 QA 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 ~~~~~~~~~~~~~~ AUTO_REVIEW_DEFAULT ................... Set `AUTO_REVIEW_DEFAULT = True` in your `local_settings.py` file in order to enable :ref:`Auto Review ` by default. 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. CONSTANT_PRECISION ................... Set the `CONSTANT_PRECISION` setting to adjust the precision for which :ref:`Constant test type ` values are displayed. (default 8) DEFAULT_GROUP_NAMES ................... A list of group names to automatically add users to when they sign up (default is an emtpy list): .. code-block:: python DEFAULT_GROUP_NAMES = ["Therapists"] 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_EXEMPT_URLS, LOGIN_REDIRECT_URL, LOGIN_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_EXEMPT_URLS = [r"^qatrack/accounts/", r"qatrack/api/*"] LOGIN_REDIRECT_URL = 'qatrack//qa/unit/' LOGIN_URL = "/qatrack/accounts/login/" NHIST ..... Adjusts the number of historical test results to show when reviewing/performing QA. 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` 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. TESTPACK_TIMEOUT ................ Change the number of elapsed seconds before exporting a TestPack will time out. Default is 30. USE_SERVICE_LOG ............... Set `USE_SERVICE_LOG` to `False` in order to disable Service Log USE_PARTS ......... Set `USE_PARTS` to `False` in order to disable the Parts app (Service Log requires `USE_PARTS = True`). 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 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 username 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 Notification specific settings ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ These settings allow you to override the default notification settings in your local_settings.py file: * `EMAIL_NOTIFICATION_USER` allows you to use a diferent user from the default set above (set to None to use `EMAIL_HOST_USER`) * `EMAIL_NOTIFICATION_PWD` password to go along with `EMAIL_NOTIFICATION_USER` * `EMAIL_NOTIFICATION_SENDER` name to use in the email "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) 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 the AD backend, you need to set the `AUTHENTICATION BACKENDS` setting as follows: .. code-block:: python AUTHENTICATION_BACKENDS = ( 'django.contrib.auth.backends.ModelBackend', 'qatrack.accounts.backends.ActiveDirectoryGroupMembershipSSLBackend', ) 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_MEMBERSHIP_REQ = [] # optional list of groups that user must be a part of in order to create account # eg ["*TOHCC - All Staff | Tout le personnel - CCLHO"] AD_CERT_FILE='/path/to/your/cert.txt' AD_DEBUG = False # turn on active directory loggin AD_DEBUG_FILE = None # log file path for debugging AD connection issues 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 `.