..  crate_anon/docs/source/website_using/rdbm_admin.rst

..  Copyright (C) 2015, University of Cambridge, Department of Psychiatry.
    Created by Rudolf Cardinal (rnc1001@cam.ac.uk).
    .
    This file is part of CRATE.
    .
    CRATE is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.
    .
    CRATE is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
    GNU General Public License for more details.
    .
    You should have received a copy of the GNU General Public License
    along with CRATE. If not, see <https://www.gnu.org/licenses/>.


Research Database Manager functions
-----------------------------------


.. _rdbm_admin_site:

RDBM admin site
~~~~~~~~~~~~~~~

This Django admin site allows the RDBM to administer all relevant aspects of
the CRATE web site.

The RDBM views are those ending in ``MgrAdmin`` within
:mod:`crate_anon.crateweb.core.admin`.


Authentication and authorization
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


Users
#####


You can add and edit users here. Most attributes are obvious but these deserve
comment:

- **Staff status:** Can the user log in to the admin sites? Usually given to
  the RDBM, researchers, and developers.

- **Superuser status:** Grants the permissions of an RDBM. Use with care.

- **Enable developer functions:** Grants the additional permissions of a
  developer (beyond those of the RDBM). Use with extreme care.

- **User is a clinician.** Enables the "clinician" features, like lookup of
  research IDs from patient IDs (for "their" patients).

- **User is an NHS consultant.** Approves the user to respond to research
  enquiries regarding CTIMPs [#ctimp]_.

There are also information flags, including:

- **Enough info for researcher status?** Unless this shows a green tick,
  information is missing, preventing the staff member from being named as the
  lead researcher for a study. This requires just a title, first name, and
  last name. (Title is the bit that isn't required to create a user, so most
  likely to be missing.)


Consent
^^^^^^^


Charity payment records
#######################


View and add records of payments made to charity (payee and amount).


Clinical team representatives
#############################


For each known clinical team, you can mark one CRATE user as the clinical team
representative. (They should have clinical authority to see identifiable
records for any patient open to that team.) This person will then become one
possible person for CRATE to e-mail about contact requests from researchers.


Consent modes
#############


View and add consent modes in CRATE's own database.

The consent mode includes two flags:

- Consent mode (red, yellow, green, unknown/NULL).
- Exclude patient from Research Database entirely?

Ancillary information includes:

- Does the patient prefer e-mail contact?
- Was the consent mode changed by a clinician's override?
- Who signed/authorized the change?

Note that the recording of consent modes is a little complex; in its
Cambridge/CPFT configuration, CRATE looks up consent modes in a recent copy of
the primary clinical records system (but failing that, CRATE's own database can
be used -- which is what this view inspects/edits).


Contact requests
################


View contact requests here. (To generate a new contact request, see
:ref:`Submit contact requests <c4c_submit_contact_request>`.)


Emails
######


View e-mails sent by CRATE that the RDBM is authorized to see. (That's not all
e-mails; certainly not those to clinicians about patients on behalf of
researchers.)


Leaflets
########


View and upload PDFs for the master leaflets used by CRATE.

**If this view is blank,** your site is not yet properly configured and you
need to run ``crate_django_manage populate`` once from the command line.

The underlying class is
:class:`crate_anon.crateweb.consent.models.Leaflet`.

Letters
#######


View letters generated by CRATE that the RDBM is authorized to see.

This also includes letters that the RDBM is required to send manually.


Patient responses
#################


View/edit patient responses (where the patient has written back to the RDBM,
after receiving information from their clinician).

The underlying class is
:class:`crate_anon.crateweb.consent.models.PatientResponse`. This object is
created when a clinician decides to send information to a patient; see
:meth:`crate_anon.crateweb.consent.models.ClinicianResponse.finalize_b`.


Studies
#######


Add and edit research studies here. In addition to basic registration information, this includes:

- the lead researcher (which CRATE user?);
- a textual summary (used to send to clinicians/patients);
- flags affecting the legal position or manner in which CRATE handles requests
  (e.g. under-16s, CTIMP, researcher prefers to approach patients directly?);
- the study details PDF (sent to patients/clinicians);
- an optional additional (subject form template) PDF for clinicians to complete
  about eligible patients, where applicable;
- other researchers (eligible to submit requests to contact patients).


Research
^^^^^^^^


Query audits
############


View the audit trail of research queries conducted via CRATE itself. The
underlying class is :class:`crate_anon.crateweb.research.models.QueryAudit`.

Note that any queries the researchers perform directly (via a direct SQL
connection to the database) will not be captured this way; enable auditing on
your database engine directly (e.g. MySQL, SQL Server) for this.


Edit sitewide query library
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Here, you can edit your site's :ref:`site queries <site_queries>`.


.. _rdbm_lookup_patient:

Look up patient ID (PID) from research ID (RID)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can use the RID, MRID, or TRID to look up patient identifiers (PID and MPID
values). This function is primarily to assist clinicians who want to see their
own patients' records within the research database, if the clinicians don't
want to do it themselves.


Charity payment report
~~~~~~~~~~~~~~~~~~~~~~

Reports on amounts due to charity and payments made, in respect of clinicians
responding to e-mails about their patients. (Payments are attributed
irrespective of the clinician's yes/no response.)


.. _rdbm_view_optouts:

Report patients to be excluded entirely from anonymised database
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Shows NHS numbers (only) of patients to be excluded entirely (fetched from the
consent-mode records), for feeding to the anonymisation system as required.


.. _rdbm_test_message_queue:

Test message queue by sending an e-mail to the RDBM
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This tests the full CRATE message system, by sending an e-mail to the e-mail
address defined by the :ref:`RDBM_EMAIL <RDBM_EMAIL>` setting in the
CRATE web config file. The sequence is as follows:

- CRATE front end → Celery → Celery broker (e.g. via AMQP to RabbitMQ)
- (via CRATE backend) Celery → picks up message from broker → CRATE e-mail
  system → authenticates with e-mail server and sends message
- E-mail system → recipient


===============================================================================

.. rubric:: Footnotes

.. [#ctimp]
    CTIMP: Clinical Trial of an Investigative Medicinal Product. See the
    UK Clinical Trials Regulations (2004, etc.):
    https://www.legislation.gov.uk/uksi/2004/1031/contents/made